Introduction:
The following document will go through the functionality found within JetTrac CallForm. This module is used to merge data from an XML file into one of a set of forms based on the amount of detail lines found within the data. For example, you can have a set of forms that are the same except one form can contain up to 10 detail lines and another can contain up to 20 detail lines. JetTrac CallForm can count the number of detail lines in the XML data file and if there are 10 or fewer use the first template, or the second if there are more than 10 detail lines.
In addition, this module also renames detail lines within an XML to give them unique field names (by adding _1, _2, etc.) at the end of the data field names prior to merging it with the form.
Technical Support:
If you need assistance in installing and configuring JetTrac CallForm™, call Pro Technology Automation, Inc. at 805-527-1248 or email us at support@protechinc.com. Please note that the JetTrac CallForm™ 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.
How to run JetTrac CallForm:
To run the program, you will need to have the following files located in the same folder:
- JTCallForm.exe
- ExitHandler.dll
In addition this module requires JetTrac PDFMerge to also be set up on the computer.
Executable files and dll files should not be edited for any reason.
Default Functionality:
JetTrac CallForm takes an input XML file and a configuration .ini file. Within the configuration .ini file you will specify a number or range of detail lines and a form to use. The module will read the input XML file and count the number or detail lines, then whichever form template specifies that number or has that number within its range will then be used to merge the data into and an output PDF will be created from the result.
In addition, the module also takes an XML that has normalized data in parent and child nodes and renames the field names to be unique. Here is an example input XML with detail lines:
<Item>
<ItemNumber>1</ItemNumber>
<Desc>Item1</Desc>
<Price>1.00</Price>
</Item>
<Item>
<ItemNumber>2</ItemNumber>
<Desc>Item2</Desc>
<Price>2.00</Price>
</Item>
<Item>
<ItemNumber>3</ItemNumber>
<Desc>Item3</Desc>
<Price>3.00</Price>
</Item>
And here is what JetTrac CallForm would change this XML to before merging it into a form:
<Item>
<ItemNumber_1>1</ItemNumber_1>
<Desc_1>Item1</Desc_1>
<Price_1>1.00</Price_1>
</Item>
<Item>
<ItemNumber_2>2</ItemNumber_2>
<Desc_2>Item2</Desc_2>
<Price_2>2.00</Price_2>
</Item>
<Item>
<ItemNumber_3>3</ItemNumber_3>
<Desc_3>Item3</Desc_3>
<Price_3>3.00</Price_3>
</Item>
Here you will notice that the module changed the XML field names to be unique and appended an underscore and an incremental number to each of them.
Job Step Configuration Window in JobConfig for JetTrac CallForm:
When setting up a job step using JTCallform 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 Output PDF. 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 XML file you want to merge with a PDF. 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.
JetTrac CallForm Command Line:
The command line to run JetTrac CallForm contains the location of the executable, the input XML file, the output merged PDF, the configuration .ini file, and the log file. The following is an example of the command line used to run this module:
“C:\JTCallForm.exe” “C:\Input.xml” “C:\Merged.pdf” “C:\Config.ini” “C:\CallForm.log”
Each part of the line is divided by spaces (the amount doesn’t matter), and contains the fully qualified file path to the file you are referencing surrounded by quotes. In the example all of the file paths reference the root of C:\, however, it is likely that none of these files will be located in the root of C:\ for your system, so this is simply demonstrating that the full file path is required.
Configuration .INI File:
The following is an example of the configuration .ini file used with JetTrac CallForm:
PdfMerge=C:\JetTrac\Programs\JTPDFMerge\PdfMerge.exe
DetailField=Detail
IsAcroFormMerge=Y
FormTable=<<
1-10,C:\Form1.pdf
11-20,C:\Form2.pdf
21-30,C:\Form3.pdf
>>
The values are as follows:
- PdfMerge – This is the fully qualified file path to the JetTrac PDFMerge executable.
- DetailField – This is the parent node in which all of the detail lines are found within the XML.
- IsAcroFormMerge – This can either be a “Y” or a “N”. If the form you are running through the this module is an AcroForm, set this to “Y”, otherwise you can set it to “N” or remove this line entirely.
- The next section must start with “FormTable=<<” on one line and end with “>>” on the last line. Between these two tags you can put any number of lines. These lines contain a number, or range of numbers and then a file path to a PDF with a comma (no spaces) separating them. The number is a single number or range of numbers which tells JetTrac CallForm that if the input XML has this many detail lines use this following template. In the example above, if the input XML has 13 detail lines C:\Form2.pdf will be merged with the data and the output will be the result.
Additional Notes:
If you are using this module just to rename fields within the XML prior to merging it with a template you can specify a single form template in the configuration .ini file and for the number add a range starting at one and ending higher than the number of detail lines that will fit on this form. This way the same form will always be used.