Perl Barcode Plug-In Demo Perl Barcode Plug-In Free Plug-In for Perl Barcodes Free Plug-In for Perl Email Tags Calculate your Return on Investment
Web Barcode for Database Apps, CompTIA Certified
Barcode Demo Free Plug-In for Perl Barcodes in PDF Calculate your Return on Investment Our Products Barcode Case Studies Frequently Asked Questions Contact Us Email Home

PDF Perl Barcode Plug-In
Installation Guide

Introduction

This Perl i-fax.com Plug-In gives your website the ability to generate barcoded documents in Adobe PDF format, that can be faxed or scanned by your customers and linked to data on your database.

The Perl/PDF version of the i-fax.com plug-in is available at Download Plug-In.


Web Barcode for Fax and Scanner

This installation manual was designed to provide software developers with an easy guide to installing the i-fax.com Plug-In on document creation systems.

If you have any questions that are not addressed by this manual or if you have suggestions on how i-fax.com Inc. could serve you better, we welcome your input at service@i-fax.com.

Note:
You can activate the i-fax.com service by signing up at https://www.secure.i-fax.com/terms.html.

There is no charge for this Plug-In. There is no charge for producing documents or web pages containing the i-fax.com barcode.

Before you can begin to receive and link documents to transactions, your i-fax.com service must be activated.

copyright © 2013 i-fax.com Inc. All rights reserved.


Table of Contents



i-fax.com Architecture


The i-fax.com Plug-In is split into two parts:

  1. The Barcode Generator
    The Barcode Generator accepts a value to encode and generates a barcode that can be inserted into a document generated by your application.

    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.

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

Perl Version of the i-fax.com Plug-In


Installing the Perl Version of the i-fax.com Plug-In onto your Website

  1. Put the .pl file in a directory where your application can find it (e.g. a directory with execution permission).
  2. 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 list of the script files provided by i-fax.com:

    ifaxpdfmerge64.pl

    The following files are for an earlier version of the barcode plugin, now deprecated:

    ifaxencode.pl
    ifaxbarcodepdf.pl
    ifaxpdfmerge.pl

    The file example.pdf is an example file for use with the PDF Merge script.

Description of the Perl Version of the i-fax.com Plug-In

Prior to creating a Barcode, your application must select a unique identifier 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 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.

To encode your identifier, call the ifaxpdfmerge64 script, passing it a unique identifier on the command line. The unique identifier must be a number between 0 and 18,446,744,073,709,551,615 (2^64-1).

The ifaxpdfmerge64 script create a barcode and adds it to the any page of the pdf file you indicate on the command line. This script outputs the newly-barcoded pdf to STDOUT so 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.

Note:
The Perl version of the i-fax.com barcode generator will only accept a 64 bit number (decimal value not greater than 18,446,744,073,709,551,615). In the event that you input a larger number, Perl will return a usage message, sends an error message to STDERR, and set a return code of 2.

Using the Perl version of the PDF Merge Utility

The Perl version of the PDF Merge Utility can be used several ways. The default method takes a file name, ID, orientation flag and page number as parameters and outputs the barcoded document to STDOUT. To put barcodes on multiple pages of the document, you may append additional occurrances of ID, orientation and page number.

Syntax: ifaxpdfmerge64.pl pdffile transID orienttop pagenum [transID orienttop pagenum ...]

  • pdffile is the full path and file name of the existing PDF you want to add the barcodes to.
  • transid is the unique identifier explained above.
  • orienttop is a value stating where on the page to place the barcode ("0" is the bottom, "1" is the top, and "2" is both bottom and top).
  • pagenum is the page number of the PDF document you want to place the barcode on.

For example, to put an i-fax.com barcode with a value "12345" on the top and bottom of the first page of a document named "example.pdf", you would do the following:

ifaxpdfmerge64.pl example.pdf 12345 2 1

If you wanted to put an i-fax.com barcode with a value "12345" on the top and bottom of the first page and an i-fax.com barcode with a value of "54321" on page four, you would do the following:

ifaxpdfmerge64.pl example.pdf 12345 2 1 54321 2 4

 

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 are generating PDFs on the fly with a library or application that can accept raw PDF streams the PDF Merge Utility can output a raw PDF stream of the barcode. See the documentation for your pdf generating software for how to use this.

Syntax: ifaxpdfmerge64.pl -r transid orienttop

  • transid is the unique identifier explained above.
  • orienttop is a value stating where on the page to place the barcode ("0" is the bottom, "1" is the top, and "2" is both bottom and top).

Browser Behavior Warning
If you are using the PDF Merge Utility 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 Utility places a barcode on the top and/or bottom of the page of the PDF document. It is important to keep this part 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 page blank (5 cm). This requirement is for the pages of the document to be barcoded only, the rest of the PDF can be formatted as you wish.

The PDF Merge Utility 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.


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:

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

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

  2. 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.
  3.  

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:

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

 

HOME | DEMO | ROI | PLUG-IN | TOOLS | TERMS OF SERVICE | OUR TECHNOLOGY | PRICING | FAQ'S | PRIVACY | CONTACT | ABOUT US

© 2013 i-fax.com Inc. All rights reserved. i-fax and the i-fax logo are trademarks of i-fax.com Inc. HP is a trademark of the Hewlett-Packard Company. All other brand or product names are trade marks or registered trade marks of their respective owners.