Introduction:

This document is a guide to installing, configuring and using the JetTrac Lookup™ Custom Agent. This document includes detailed instructions for installation and configuration in the Adobe Central Document Server Job Management Database and example files to help you see how the program works.

Background:

JetTrac Lookup™ allows dynamic processing of any type of data needed in a Adobe Central Document Server application, particularly useful for processing multiple bank accounts for a check application within a Adobe Central Output Server process. This allows for one input data file that is produced by the Line of Business application (e.g. Oracle Financials, J.D. Edwards, SAP, etc.) to have checks that need to be written on multiple bank account to dynamically call the correct information on a check by check basis. This way only one form and one TDF file needs to be designed that is used for all bank accounts.

Please note that the documents (e.g. checks) will print in the same order as the input data file. If you want to print groups of checks together based on dollar ranges to print in batches, then you can implement our JetTrac GroupRange™ product which will print checks in groups, e.g. all checks requiring manual signatures would be printed in one group so no manual sorting of checks would be required.

JetTrac Lookup™ 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 Lookup Installation and User Guide for AS/400 for help on AS/400 installation and configuration.

Technical Support:

If you need assistance in installing and configuring JetTrac Lookup™, call Pro Technology Automation, Inc. at 805-527-1248 or email us at support@protechinc.com. Please note that the JetTrac Lookup™ 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.

INSTALLATION AND CONFIGURATION OF JETTRAC LOOKUP™:

 

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.protechinc.com on the JetTrac page.

Installing JetTrac Lookup:

After the JRE is installed, you are ready to proceed to the JetTrac Lookup 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:
Folder name Filename Description

C:\JetTrac\JTLookup JTLookup.jar JetTrac Lookup executable program file

C:\JetTrac\JTLookup JTLookup.ini JetTrac Lookup INI file

C:\JetTrac\JTLookup JTLookup.db lookup database file

C:\JetTrac\JTLookup JetTracLookupUserGuide.pdf – this document

C:\JetTrac\JTLookup lookup.lic JetTrac License Key file

C:\JetTrac\JTLookup Run JTLookup.bat Sample DOS batch file for testing

Configuring the JetTracLookup.ini file:

There are two main steps to complete the configuration of JetTrac Lookup. The first is to set up and test the JetTracLookup.ini and JetTracLookup.db files. The second is to set up a task and job step in the Job Management Database in Adobe Central Control to call JetTrac Lookup™ at the correct time.
To set up the INI file, open JetTracLookup.ini. A sample looks like this:
StartRec

keyval

trigger

c:\JetTrac\JTLookup\JTLookup.db

CheckNumber

N

~~

Field name of first field in each record

Field name of key value (or =keyValue for fixed keys)

Field name of trigger field (insert after this)

Path to lookup.db file

Field name for zero-pad or !!

Y = stop on “not-found”, N = continue on “not-found” but don’t insert any fields or do any zero fill. D = default on “not-found” and use the very first row of the DB file for processing

The first five lines are values that JetTrac Lookup 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 The field name of the first field in each record in the input Field Nominated File, or an exact string if the first thing on the line is a ^

Line 2 The field name of key value (or =keyValue for fixed keys) A fixed key would allow you to specify in this ini file a specific lookup value. This would not change in any given job step. This would allow you to print using several different jobs, all of which would pull from one .db file. This field MUST be only one line long.

Line 3 The field name of trigger field (insert after this). The fields found according to the key will be inserted after this field. This cannot be the same as the key value (Line 2). If this line is blank, the fields will be inserted immediately after the key field.

Line 4 The fully-qualified lookup db file name. This is decribed in section section 2.4.

Line 5 The field name for zero-pad or !! This will allow you to add zeros to any field value in the data file. This is most often used for check number fields in the MICR line as they often need leading zeros that do not appear in the normal output. Further information about this is included as a part of the JetTrac Lookup.db file. If zero padding is not desired, two exclamation marks, !! need to be entered.

Line 6 is an option on how to handle processing if a lookup in the DB file is attempted but there is not match found. Y = stop on “not-found”, N = continue on “not-found” but don’t insert any fields or do any zero fill, D = default on “not-found” and use the very first row of the DB file for processing.
Important Note: The order of the fields in the Field Nominated File is critical. The field name of the first field in each record must be first in the Field Nominated File, then the Key Value line Line 2 must occur after that, then the Zero Pad field (if used) must occur after the Key Value field, then the Trigger field from Line 3 must occur after the Zero Pad field.

Configuring the JetTracLookup.db file:

The JetTracLookup.db file contains one or more records that dynamically insert(s) variable information onto the output depending on a key value, like department number. JetTrac Lookup takes the value from the key value field and when it finds a match in the .db file, it inserts the field names and values that match that value. This key value can come from the Field Nominated File or it can be hardcoded in the JetTracLookup.ini file. Here is an example:
4

10

^field CheckDigits|^field Address|^field City|^field RoutingNum|

AAA|10|124 Locust Lane|Simi Valley, CA|94950934-3223|

AAB|11|1824 Sigjun Circle|Sugar City, ID|03385492|

AAC|5|1 Infinite Loop|Cupertino, CA|0097-654333|

Each line of the .db file has the following purpose:

Line 1: This is the number of fields in each record of the DB file

Line 2: This is the maximum number of entries in the lookup table. If this number is less than the number of entries, the remaining entries will be ignored. JetTrac Lookup uses this number to optimize memory allocation and processing speed.

Line 3: This is the line where all of the output field names are declared. This also allows to specify whether they be ^field or ^global. The first field also specifies the name of the field that will contain a number to tell JetTrac Lookup the number of digits to place in the zero-padded field. Each subsequent field is separated by a pipe | character (usually the shift of the backslash key) and the line must end with a pipe character.

Lines 4-n: These lines contain the lookup value to match followed by the values to insert in the fields specified in line 3 above. Each value is separated by a pipe | character (usually the shift of the backslash key) and each line must end with a pipe character. The first value in each line is the lookup value that must match the value found in the key field specified in the .ini file. After the key value, the fields follow in order corresponding to the field names specified in line 3. There should be the same number of field values on these lines and there are field names on line 3.
To create a multiple line field, simply place a tilde ~ between the desired data. This will not change the way that JTLookup processes the data, but JFMerge will interpret and show this as a carriage return. (If you need to use tilde for some other reserved use, you can pick another character and use a –anl[x] option in the jfmerge.exe command line to change the default new line character. You can also change the default in the jfmerge.ini file.
A note on check number zero padding: If you are using check number padding, the number representing the length of the check number must immediately follow the lookup value, as the first “field” to be inserted. In order to use the padded check number in one of the inserted field values for that same key value, use a “@” character in the desired spot. The @ will be replaced with the padded check number. The fieldname used for the field containing the number of padding digits is not required, but the place (as the first field inserted) is reserved.

Job Step Configuration Window in JobConfig for JetTrac Lookup:

When setting up a job step using JTLookup in JobConfig the only lines of the config you need to worry about are the first and the last two, the Config file, the Input XML and the Output XML. If left as an asterisk * the input will be whatever file is in the data folder that triggered the job running. This works well if it’s the first step but if the input is also the output of a previous job step you would need to specify the fully qualified path of the input xml. All other fields should be filled with the fully qualified path to the intended file. Eg: C:\JetTrac\…\input.pdf
In JobConfig, file paths entered should not be in quotes.

As with all modules, there is a dropdown to select whether or not the job should stop completely if this step fails. If you select Yes, any error will terminate the job process and write to the log file what happened, if no, then the job will try to continue anyways. However if any steps further down the line rely on the output of a job set to not stop on error, they may not work properly.

For more specifics go to the JetTrac Field ServiceJobConfig page.

The JetTrac Lookup Command Line:

JetTrac Lookup is a Java program and must be run from withing 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 [path to java.jar file] [input fnf] [output fnf] [ini file] [ini flag] [log file]
A sample is:

java -jar -DJETTRACLF=”C:\JetTrac\JobController\License\JetTrac.lic” “C:\JetTrac\JTLookup.jar “C:\JTLookup_Input.xml” “C:\JTLookup_Output.xml” “C:\JTLookup_config.ini” INI “C:\JTLookup.log”

The input file is the Field Nominated File created by the previous job step, which often is the Transformation Agent, though may be another custom agent. The output file is the Field Nominated File output from JetTrac Lookup with the added fields. The INI file is the file with all the definitions as specified in Section 2.2. The output file is the Field Nominated File output from JetTrac Lookup with the added fields. The ini flag is a way to feed the lookup value directly off of the command line. This supercedes any value found in the key and always inserts the value(s) that correspond that the key value found on the command line. However, if you do not wish to use this feature, use INI as the value on the command line and the key value(s) will be looked up from the incoming data stream. The log file is the fully qualified Adobe Central Output Server logfile name.
Section 2.7 will instruct you how to implement this command line for use with Adobe Central Output Server.

The JetTrac Lookup License File:

As with all JetTrac products, JetTrac Lookup is protected from piracy by the JetTrac License Manager system. This system locks JetTrac Lookup 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 Lookup 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 Lookup custom agent in Adobe Central Control for Windows platforms:
1. Start Adobe Central Control
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: JTLookup

Program name: java

Program options: -DJETTRACLF=c:\jettrac\license\lookup.lic –jar c:\JetTrac\JTLookup\JTLookup.jar @InFile @OutFile @PreambleName INI @LogFileName

Comment: JetTrac Lookup Custom Agent by Pro Technology
Rather than having JTLookup read the key values out of the FNF stream (which is default), it is possible to force JTLookup to always use one value for the key, which is often in that case passed from the job card line as an Other Job Token. If this is the way that you need to use JTLookup, replace the INI in the command line above with the Central system variable: @OtherJobTokens.
4. Click OK to save the Task Definition.
5. Now you must create a job step that calls the JetTrac Lookup task. This would be one of the job steps in the complete job you are setting up. To set up a new job, from Adobe Central Control main screen click File, Job Management Database, Jobs, then New Job. Define the rest of the steps that as needed. If a JFTrans and a JFMerge Job Step exist, JetTrac Lookup will always go after JFTrans and before JFMerge.
6. 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.

Configuring the Job in the Job Management Database:

1. Now you must create a job step that calls the JetTrac Lookup task. This would be an intermediate step in the complete job you are setting up (e.g. you would run the Transformation Agent First, then JetTrac Lookup, then the Print Agent).

2. 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 Adobe Central Output Server. We will assume that you already have a job set up and you are adding the JetTrac Lookup 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 JTLookup

On Error – Select S to Stop the Job if there is an error in JetTrac Lookup

Input File – Select the output file letter of the previous task

Output file – Select the next letter in the alphabet after the Input file.

Form File – put the fully qualified name of the INI file

Printer Name – leave it as *

Macro Number – leave it at 1

Load Flag – leave it at T

Comments – type in a description like “Performs Data Lookup”

3. Close the job step window.

4. In the job definition window, select the JTLookup 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 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.

RUNNING JETTRAC LOOKUP™:

Files Required to Run:

• JTLookup.jar
• JTLookup.db
• JTLookup_config.ini

 

How JetTrac Lookup™ is triggered:

As JetTrac Lookup is set up as one of the steps of a job, whenever a job is triggered that needs to use JetTrac Lookup, the processing happens automatically.

Adobe Central Output Server Log File:

JetTrac Lookup™ conforms to all Adobe 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 Lookup:
19991018160126 JetTrac Lookup : processing completed, 50 lines.