Introduction:
This document is a guide to installing, configuring and using the JetTrac HTML Merge™ Custom Agent. This document includes detailed instructions for installation and configuration in the JetForm Central Job Management Database.
Background:
JetTrac HTML Merge™ gives JetForm Central quick and easy HTML Output capability. This makes use of standard field-nominated files and a pre-made HTML form with fields delineated in a special way. This allows you to design your HTML form in any standard HTML editor such as MS FrontPage 2000 or Word or any product you choose. This HTML output can then be directed out as the body of an E-mail, possibly using JetTrac E-mail or fed straight to a web user using a CGI script on your web server.
JetTrac HTML Merge™ is written in Java so it will run on any platform that supports Java, including, among others, Windows, UNIX, and AS/400. See the JetTrac HTML Merge Installation and User Guide for AS/400 for help on AS/400 installation and configuration.
For additional information on Java and JetTrac Java products, see the document JetTrac Java and Licensing Considerations available from the Pro Technology website, www.protechinc.com.
Technical Support:
If you need assistance in installing and configuring JetTrac HTML Merge™, call Pro Technology Automation, Inc. at 805-527-1248 or HTML E-mail us at support@protechinc.com. Please note that the JetTrac HTML Merge™ 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.
What JetTrac HTMLMerge does:
JetTrac HTMLMerge is a very simple text merge utility. It works in this manner:
1. You create an HTML page in any HTML editor. You can design it any way you want. This is called the HTML template.
2. In the places where you want dynamic data from your field-nominated file to appear, you insert the field names in the document. For example, for a fnf field name of DOCDATE, in your HTML template, you would insert @JetTrac.Date.
3. When JetTrac HTML Merge runs, it will create a table of the fields it finds in the field-nominated file and then as it goes through the HTML template, it will replace the @JetTrac codes with the values found for those fields in the field-nominated file.
4. If you have a multipage document with print-image-formatted detail blocks, you can have Jet Trac HTML Merge automatically stack all of your successive detail blocks together by entering the field name of the successive detail blocks (must all be the same name) and by calling the name in the HTML template @JetTrac._DETBLOCK. JTHTMLMerge will then replace all of the static header and footer fields and string together as many detail block fields as it finds.
INSTALLATION AND CONFIGURATION OF JETTRAC HTML MERGE™:
Installing Java:
Refer to the document JetTrac Java and Licensing Considerations for installing the Java Runtime Environment (Java) and generating a site code for your site. It is available on the web at www.protechinc.com on the JetTrac page.
Installing JetTrac HTML Merge:
After Java is installed, you are ready to proceed to the JetTrac HTML Merge files themselves. You will receive an installation EXE file. Simply double click on the EXE file to unzip it and follow the instructions. The following files will be installed in the c:\jfsrvr\CustomAgents\JTHTMLMerge directory:
Filename Description
RunJTHTMLMerge.bat Batch file for testing
JTHtmlMerge.jar JetTrac HTML Merge executable program file
JTHTMLMerge.ini JetTrac HTML Merge INI file
Htmerge.lic JetTrac HTML Merge license file for your computer
JTHTMLMergeSamplein.html Sample HTML Input file for JTHTML Merge
JTHTMLMergeSamplein.fnf Sample Field-nominated input file for JTHTML Merge
JetTracHTMLMergeUserGuide.pdf This document
Configuring the JetTracHTMLMerge ini file:
There are two main steps to complete the configuration of JetTrac HTML Merge. The first is to set up the JTHTML Merge.ini file. The second is to set up the tasks and job steps in the Job Management Database in JetForm Control to call JetTrac HTML Merge™ at the correct time.
The ini file of JetTrac HTML Merge has only two lines. Here is a sample:
C:\jfsrvr\CustomAgents\JTHTMLMerge\OutputTemplate.html
DETBLOCK
~~
1. Name of HTML Template.
2. Name of Detail Block field.
The double tildes (~~) are for separation. All lines above the tildes are read by JTHTMLMerge and the lines below are simply for internal documentation. Here is more info on the two lines:
Line 1: This is the HTML file that JTHTMLMerge will use as a template and will insert all of it’s fields into.
Line 2: This is the name of the repeating detail block field.
The JetTrac HTML Merge Command Line:
JetTrac HTML Merge is a Java program and must be run from within the Java Runtime Environment that we installed in section 2.1. Assuming that you already have Java installed on your system, the format of the command line is:
java –jar [path to java.jar file] [input fnf] [output html file] [ini file] [log file]
A sample is:
java -jar JTHtmlMerge.jar Input.dat Output.html JTHtmlMerge.ini jfserver.log
Section 2.7 will instruct you how to implement this command line for use with JetForm Central.
The JetTrac HTML Merge License File:
As with all JetTrac products, JetTrac HTML Merge is protected by the JetTrac License Manager system. This system locks JetTrac HTML Merge 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 either physically or through E-mail.
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 HTML Merge 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. If it doesn’t match, JetTrac HTML Merge will end, with a message telling you to get a valid license file from Pro Technology Automation.
Refer to the document JetTrac Java and Licensing Considerations for further information.
Configuring the task in the Job Management Database:
To add the JetTrac HTML Merge custom agent in JetForm Control for Windows platforms:
1. Start JetForm Control by clicking Start, Programs, JetForm Central, JetForm Control (may be slightly different for your installation). You will get the following screen:
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: HTMLMerge
Program name: java -jar c:\jfsrvr\CustomAgents\JTHTMLMerge\JTHTMLMerge.jar
Program options: @Infile @Outfile @MDFName @LogFileName
Comment: JetTrac HTML Merge Custom Agent by Pro Technology
It will look like this:
4. Click OK to save the Task Definition.
5. Close out of the Task Definition window.
2.7 Configuring the Job in the Job Management Database
1. Now you must create a job step that calls the JetTrac HTML Merge task. To set up a new job, from JetForm Control main screen click File, Job Management Database, Jobs, then New Job. Define the rest of the steps that as needed. Under most circumstances, JetTrac HTML Merge will followed by some other step, such as JetTrac E-mail to send out the body of the message.
2. From the main screen of JetForm Control, click File, Job Management Database, Jobs. You will get a list of all jobs you have set up in JetForm Central. We will assume that you already have a job set up and you are adding the JetTrac HTML Merge task. Click on the Job that you want to add notification to, then click “New Step”. The New Job Step screen will appear.
The following are the fields that you need to fill in:
Task ID – from the drop down list, select HTMLMerge
Input File – Use the letter output from the last job
Output file – Use the letter that will be input into the next job. You might have to
On Error – Select S to Stop the Job if there is an error in JetTrac HTML Merge
Form File – put the fully qualified name of the INI file
Preamble file – This should be *
Printer Name – leave it as *
Macro Number – leave it at 1
Load Flag – leave it at T
Comments – type in a description like “Creates HTML Output”
It will look like this:
3. Close the job step window.
4. In the job definition window, select the JTHTML Merge step and make sure that it is the last step in the job by putting it at the bottom of the list with the up and down arrow buttons in the window.
5. Close all windows, get back to the main JetForm 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.
RUNNING JETTRAC HTML MERGE™:
Submitting transaction files to JetForm Central:
To submit a transaction file to JetForm Central, you place a data file into the Collector Directory. There are a number of ways to do this depending on the platform that you are running JetForm Central. You can FTP the file, use the JetForm Print Processor, use Named Pipes or simply copy the file to the Collector Directory.
JetForm Central Log File:
JetTrac HTML Merge™ conforms to all JetForm requirements as a Custom Agent. It writes a status to the log file and creates the JETFORM.RSP. Here is a sample entry in the log file for a successful run of JetTrac HTML Merge:
19991014121616 JetTrac HTML Merge : processing completed
991014 12:16:16 C:\JFSRVR\jfsrvr.exe: [400]–> returned [0] JetTrac HTML Merge : processing completed.