JetTrac DBConnect

Introduction:

This document is a guide to installing, configuring and using the JetTrac DBConnect™ 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 DBConnect™ is a complete system for the production extraction of database information within an Adobe Central job. It consists of four parts:

a. JetTrac DBInfo – “audit log” that interrogates a database and reports on its structure. This is particularly useful for integrating with databases that have not been used or tested with DBConnect before.

b. JetTrac DBConfig – graphical interface to define the links to the database, the links within the database and what data you want to pull.

c. JetTrac DBConnect – The production program that runs within Adobe Central that extracts the information out of the database based on the information in an INI file created by DBConfig.

d. JetTrac DBExtract – a separate production program that runs within Adobe Central that allows a pre-built SQL Select statement to be executed and a Field Nominated File automatically created.

JetTrac DBConnect™ is written in Java so it will run on any platform that supports Java. If you wish to run DBConnect on a platform other than Windows please contact us first at 805-527-1248 to discuss your particular needs.

Technical Support:

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

 

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.

Installing JetTrac DBConnect:

After the JRE is installed, you are ready to proceed to the JetTrac DBConnect 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:
File Description

JTDBConnect.jar JetTrac DBConnect executable program file

DBConfig.jar DBConnect config program

JTDBConnect.ini sample JetTrac DBConnect INI file

JTDBConnect.mdb sample database file

JetTracDBConnectUserGuide.pdf this document

conect.lic JetTrac License Key file

Run JTDBConnect.bat Sample batch file for testing

Configuring JetTrac DBConfig:

JetTrac DBConnect is configured by means of the DBConfig program. DBConfig is a program that will help you explore your databases and establish linkages, etc. Before you can use DBConfig to set up the database extractions you need, you must do two things: (A) you must have a working knowledge of your database structure, and (B) you must set up a DSN for your database in ODBC.
Create a DSN

Assuming you are comfortable with locations of data in your database, let’s set up a DSN to point to it. Go to Start, Settings, Control Panel, Administratrive Tools, Data Sources (ODBC). Click the System DSN tab and then click the Add button. Select the Driver for the database you wish to access (you may need to install the ODBC driver for your database), and click Finish. The Setup screen for your database should appear. Enter the name of the DSN you would like, and enter the rest of the information. Since this will vary according to the database, you may need your DBA’s help to configure the rest of the info.

Configure DBConfig

Once you have a DSN set up for your database, double-click on DBConfig.jar to run the program. You may have to launch if off of the command line if it doesn’t start. The command line would be java –jar DBConfig.jar. You should see the program screen, which looks like this:
Follow these steps:

1. Enter the field name of the key field from your FNF data stream at “Data file Key Field Name.”

2. Select the data not found behavior of JTDBConnect under Mission Data Handling. The choices are Stop (meaning terminate the program), Skip (meaning ignore the error and continue), and Default (meaning insert a static value). If you pick Default, then enter the static default value you want entered in the field beside the drop down.

3. Select the DSN pointing to your database by clicking Set DSN. Enter the DSN name and the user and password for the database, if one exists. DBConfig will then read in the names of the tables in your database.

4. Click the Add Table button. A list of your tables comes up. You should first select the table that you wish to link to from you FNF datastream. You can link other tables from there later. Once you have selected the table, it should appear as a tab in the window. DBConfig has retrieved the names of all of the fields in the table.

5. Link this table to your FNF datastream by selecting Data file key as shown to the right. Then at to field in this table, select the field in this table whose values correspond to the values found in the key field in your FNF stream.

6. Select the fields you may want to extract from this table by checking the box next to each field. You can change the name of each field as it will appear in your FNF datastream by changing the name in the column on the right. Just click to edit the name.

7. To link in another table, click Add Table again and pick that table. That table will be added as another tab behind the current table’s tab. Click the new table’s tab to bring it to the front. Link the new table to the first table by either (A) linking it back to the Data file key as before or (B) linking it to the other table in the following manner.

8. At Link Table, specify the first table’s name. At Link Field, specify a field from the first table whose values correspond to the values found in a field in this new table. Then select the name of that matching field in this table at the to field in this table blank as shown.

9. Select the fields you may want to extract from this table by checking the box next to each field as before. You can change the name of each field as it will appear in your FNF datastream by changing the name in the column on the right. Just click to edit the name.

10. Continue with as many tables and fields as you need.

11. When you are done, select Save from the file menu and save the file, probably with a file extension of .ini

The JetTrac DBConnect Command Line:

JetTrac DBConnect 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] [log file]

A sample is:

java –jar “c:\JetTrac\JTDBConnect.jar” “test.in” “test.out” “JTDBConnect.ini” “jfserver.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 DBConnect 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 DBConnect with the added fields. The log file is the fully qualified Adobe Central Output Server logfile name.
Section 2.6 will instruct you how to implement this command line for use with Adobe Central Output Server.

The JetTrac DBConnect License File:

As with all JetTrac products, JetTrac DBConnect is protected from piracy by the JetTrac License Manager system. This system locks JetTrac DBConnect 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 DBConnect 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 DBConnect 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: JTDBConec

Program name: java

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

Comment: JetTrac DBConnect Custom Agent by Pro Technology
Click OK to save the Task Definition.
4. Now you must create a job step that calls the JetTrac DBConnect 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 DBConnect will always go after JFTrans and before JFMerge.
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.

Configuring the Job in the Job Management Database:

1. Now you must create a job step that calls the JetTrac DBConnect 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 DBConnect, 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 DBConnect 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 JTDBConnect

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

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 Database Lookup”
3. Close the job step window.
4. In the job definition window, select the JTDBConnect 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.