Introduction:
This document is a guide to installing, configuring and using the JetTrac LoadBalance™ Custom Agent. This document includes detailed instructions for installation and configuration in the Adobe Central Job Management Database.
Background:
In a production output process there may be a requirement to print a large quantity of documents in a short period of time. If the laser printer is not fast enough then multiple printers may be needed in order to print all of the documents fast enough. However, only one output stream can be generated from each merge. JetTrac LoadBalance provides intelligent splitting of the data stream so that the job can be directed to several printers at once and/or several instances. If Central is set up with multiple instances then concurrent processing can occur so all printers are going at the same time. It serves to address printer load balancing.
JetTrac LoadBalance™ splits the number of documents (records) found in one input Field Nominated File to multiple output Field Nominated Files by predetermined percentages. You control exactly how many printers will be used, the percentage of documents going to those printers and what directories the output files will be written to. JetTrac LoadBalance runs as a production process, completely unattended. Each application (e.g. A/P Checks, Invoices, etc. can have their own INI files so you can control how many printers each one will print to.
Each split output fnf file has its own job card so that it can be placed back in a Central collector directory for processing output to the predetermined selection of printers/destinations.
There is a summary report generated for the batch of documents processed. It includes the number of documents printed, where they were printed and a total page count.
JetTrac LoadBalance™ is written in Java so it will run on any platform that supports Java, including, among others, Windows and most UNIX platforms.
Technical Support:
If you need assistance in installing and configuring JetTrac LoadBalance™, call Pro Technology Automation, Inc. at 805-527-1248 or email us at support@protechinc.com. Please note that the JetTrac LoadBalance™ license fee does not cover configuration services and technical support so there may be an additional charge. Please ensure you read these instructions carefully before calling for technical support.
Adobe/Accelio/JetForm/version Note:
This document applies the same to all versions of Central, from JetForm, Accelio, and Adobe. This document assumes that you will be installing JetTrac LoadBalance under Adobe Central 5.5 or later. If you need to install it on an earlier version of Central, simply adjust the paths given, or contact ProTechnology for assistance.
1.6 Typical Adobe Central job flow using JetTrac LoadBalance
This is a diagram showing typical job flow incorporating the JetTrac LoadBalance™ custom agent as the job step following data transformation. In this application, the output file has a unique string that identifies the start of a document. An assigned number for a count separates the documents into equal batches (the last file being the documents remaining over the count number) or the documents within the FNF are counted entirely through the end of the file then separated by percentages of the total count.
INSTALLATION AND CONFIGURATION OF JETTRAC LOADBALANCE™:
Installing Java:
Refer to the document What you need to know about Java and JetTrac Licensing for installing the Java Runtime Environment (Java or JRE) and generating a site code for your site. It is available on the web at www.jettrac.net on the Products page. If installing on a Windows platform, we highly recommend you use version 1.5 or later of the JRE, though in some cases, earlier versions will work. Contact us for further questions.
Installing JetTrac LoadBalance:
After the JRE is installed, you are ready to proceed to the JetTrac LoadBalance files themselves. The files you need are:
Filename Description
JTLoadBalance.jar JetTrac LoadBalance executable program file (java)
JTLoadBalance.ini JetTrac LoadBalance INI file
Run JTLoadBalance.bat Sample DOS batch file to test JTLoadBalance
JTLoadBalance.lic JetTrac LoadBalance license key file (only obtained from Pro Technology)
Configuring the JetTracLoadBalance.ini file:
There are two main steps to complete the configuration of JetTrac LoadBalance. The first is to set up the JetTracLoadBalance.ini file. The second is to set up a task and job step in the Job Management Database in Adobe Central Control to call JetTrac LoadBalance™ at the correct time.
To set up the INI file, open JetTracLoadBalance.ini. A sample looks like this:
^page 1
P
^job SummaryReport -z\\protechnt\lexmark
summary_
Output1.dat|^job apchecks -zPrinter1|Bob’s printer|30
Output2.dat|^job apchecks -zPrinter2|John’s printer|30
Output3.dat|^job apchecks -zPrinter3|Debbie’s printer|40
~~
Line 1 field or ^String that indicates first field in each document
Line 2 P Flag for specifying percentage(s)
Line 3 ^job card or text file that contains job card and whatever else is written at the top of Summary Report (e.g. Header/Title information)
Line 4 Collector Directory and prefix name to write Summary Report output file
Lines 5-nn Percentage output lines
Each line contains (pipe-delimited):
Field 1 – Fully qualified output filename
Field 2 – Job card content written on line 1 of split output FNF
Field 3 – Readable name for printer
Field 4 – Percentage of documents to go to this printer (percentages must add up to 100 or program will fail!)
The first 5 lines are values that JetTrac LoadBalance reads. The rest of the lines are internal documentation to prompt you for what goes on each line. The double-tilde (~~) serves to separate the code lines from the explanations.
Line 1 is the unique string field name or ^String that indicates first line of each record in the input Field Nominated File
Line 2 Flag for splitting the FNF by a percentage (P) from the JTLoadBalancePrinter.ini file
Line 3 ^job card or a fully qualified text file that contains a ^job card and whatever else is written at the top of the Summary Report (e.g. Header/Title information) FNF
Line 4 Collector Directory and prefix name to write Summary Report output file
Line 5 Repeated for how ever many printers will be used on processing.
Each line contains (pipe-delimited):
Field 1 – Fully qualified output filename
Field 2 – Job card content written on line 1 of split output FNF
Field 3 – Readable identification for printer appearing on Summary Report
Field 4 – Percentage of documents to go to this printer (percentages must add up to 100 or program will fail!)
The JetTrac LoadBalance Summary Report:
The Summary Report is an standard Field Nominated file and is constructed as follows:
1. The filename prefix is specified in line 4 of the INI file
2. Either the job card from line 3 or if line 3 doesn’t begin with ^ it is the path to a file that is inserted before the rest of the summary report that contains a ^job card as the first record.
3. The rest of the file would consist of:
- Comment: These fields and variables are repeated for each printer
^field Summary_Report_Filename
The output filename as specified in field one of lines 5-nn in the ini file
^field jobcard
The first line as specified in field two of lines 5- nn in the ini file
^field Printer_Name
Readable name for printer as specified in field three of lines 5- nn in the ini file
^field Printer_Percentage
Specified in field four of lines 5- nn in the ini file
^field Document_Range
The starting document number then a dash followed by the ending document number that went to each fnf file.
^field Total Documents
The actual number of documents split into this fnf file
#Comment Repeated back to top for each of the printer lines 5- nn
The very end of the Summary Report contains the total number of documents processed:
^field Summary_Report_TotalCount
Total number of documents counted
An example Summary Report FNF file would look like this:
^job SummaryReport -z\\protechnt\lexmark
^field Summary_Report_Filename
Output1.dat
^field jobcard
job apchecks -zPrinter1
^field Printer_Name
Bob’s printer
^field Printer_Percentage
30
^field Document_Range
1-3
^field Total_Documents
3
^field Summary_Report_Filename
Output2.dat
^field jobcard
job apchecks -zPrinter2
^field Printer_Name
John’s printer
^field Printer_Percentage
30
^field Document_Range
4-6
^field Total_Documents
3
^field Summary_Report_Filename
Output3.dat
^field jobcard
job apchecks -zPrinter3
^field Printer_Name
Debbie’s printer
^field Printer_Percentage
40
^field Document_Range
7-10
^field Total_Documents
4
^field Summary_Report_TotalCount
10
The JetTrac LoadBalance Command Line:
JetTrac LoadBalance is a Java program and must be run from within the Java Runtime Environment. Refer to section 2.1 for more information on acquiring and installing Java. Assuming that you already have Java installed on your system, the format of the command line is:
java –jar –DJETTRACLF=[path to JTLoadBalance license file] [path to JTLoadBalance.jar file] [input fnf] [ini file] [log file]
A sample is:
java –jar –DJETTRACLF=”c:\jettrac\license\load.lic” c:\JetTrac\JTLoadBalance\JTLoadBalance.jar “test.fnf” “JTLoadBalance.ini” “jfserver.log”
Section 2.7 will instruct you how to implement this command line for use with Adobe Central.
The JetTrac LoadBalance License File:
As with all JetTrac products, JetTrac LoadBalance is protected from piracy by the JetTrac License Manager system. This system locks JetTrac LoadBalance for use exclusively to one server or system in your organization. It works in this manner:
1. You run JetTrac SiteCode on your computer and generate a unique site code file for your system.
2. You send that site code file to Pro Technology Automation.
3. Pro Technology uses your site code file to generate a product license key file.
4. Pro Technology sends the product license key file back to you.
5. When JetTrac LoadBalance runs, it scans the system and compares the tokens it finds with the tokens found in the license key file, and if they match, it runs normally.
Refer to the document What you need to know about Java and JetTrac Licensing for further information.
Configuring the task in the Job Management Database:
To add the JetTrac LoadBalance custom agent in Adobe Central Control for Windows platforms:
1. Start Adobe Central Control by picking it from the Start menu.
2. Add a new Task by clicking on File, Job Management Database, Tasks.
3. Create a new task by clicking New Task. Set up the Task Definition with the following information:
Task ID: JTLoadBal
Program name: java
Program options: –jar –DJETTRACLF=c:\JetTrac\license\load.lic c:\JetTrac\JTLoadBalance\JTLoadBalance.jar @InFile @MDFName @LogFileName
Comment: JetTrac LoadBalance Custom Agent by Pro Technology
4. Click OK to save the Task Definition. Close out of the Task Definition window.
5. Now you must create a job step that calls the JetTrac LoadBalance task. This would be one of the job steps in the complete job you are setting up.
If, for instance there is a job that runs a JFTrans step and then a JFMerge, then we will need to split the job into at least two jobs. JetTrac LoadBalance would run after the JFTrans step. The JFMerge step will then be put into a new job.
The job will be named according to what we give the name of the job in the ini file, explained in section 2.3 above. This would allow each of the output files created by JetTrac LoadBalance to be individually picked up and processed one-by-one by Central. The newly created split files would then print to the printers assigned in the JTLoadBalance.ini file.
6. From the main screen of Adobe Central Control, click File, Job Management Database, Jobs. You will get a list of all jobs you have set up in Central. We will assume that you already have a job set up and you are adding a LoadBalance step. Click on the Job that you want to split, then click “New Step”. The New Job Step screen will appear. Following are the fields that you need to fill in:
Task ID – from the drop down list, select JTLoadBal
Input File – the value that goes here would be a single letter which is the output from the previous job step. If your current job had two steps, JFTRANS and JFMERGE, then the output from JFTRANS was “A”. If you now want to sort this file, then the Input file for JetTrac LoadBalance would be A. If you have questions about how this works, contact your Adobe Central support person.
Output file – leave this as *
On Error – Select S to Stop the Job if there is an error in JetTrac LoadBalance
Form File – this field would contain the fully qualified INI filename that you have set up for JetTrac LoadBalance, e.g. c:\JetTrac\JTLoadBalance\JTLoadBalance.ini
Preamble file – This should be * Delete whatever else might appear here.
Printer Name – leave it as *
Macro Number – leave it at 1
Load Flag – leave it at T
Comments – type in a description like “Splitting batch for printer load balancing”
7. Close all windows, get back to the main Adobe Central Control screen and update the Job Management Database by clicking on Control, Reload Job Management DB. When asked if you want to save changes to the Job Management Database, click Yes.