JetTrac JobController

Introduction:

This document is a guide to installing, configuring and using the JetTrac JobController™ application. This document includes instructions for installation and configuration of JetTrac JobController and the Job Management Database.

Background:

JetTrac JobController™ enables the system to execute predefined jobs from a Job Management Database (jmd) definitions file. The jmd file is a series of statements indicating sequences of tasks that will be executed upon identification of a job. A job is identified by a term known as “JobName”; JobName is typically specified within each document being processed.

JetTrac JOBCONTROLLER™ is written in Java so it will run on any platform that supports Java, including, Windows, UNIX, and Linux. This guide will assume a Windows installation, but the information herein can easily be adapted for UNIX or Linux.

For additional information on Java and JetTrac Java products, see the document What you need to know about JetTrac Java and Licensing available from the JetTrac website, http://www.JetTrac.com .

Technical Support:

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

Installing Java:

Refer to the document What you need to know about JetTrac Java and Licensing for further information about installing the Java Runtime Environment (Java or JRE) and generating a site code for your site. It is available on the web at java.sun.com or www.JetTrac.com. We highly recommend you use the 32 bit version 1.5 or later of the JRE, though in some cases, other versions will work. For your particular system, you might need to consult the Command line examples used in this guide are for java 1.5 or later. Contact us for further questions.

Installing JetTrac JobController:

For installation on a Windows platform there is a Windows installer that will verify all required system components and install the components and JetTrac JobController.

Running JetTrac JobController:

There are two ways that JetTrac JobController can be started:

  • From a Windows service for production environments. We have a separate installer that will install the Windows server for JetTrac JobController
  • From a bat file for development and test environments as described on the next page.

 

With startServer.bat

startServer.bat sets up the working environment and executes the program necessary to run JobController. Assuming you installed JetTrac Field Service to C:\JetTrac you can find startServer.bat at C:\JetTrac\JobController. See below for an example of startServer.bat:

@set JCHOME=C:\JetTrac\JobController
@set JCLICENSE=%JCHOME%\License\JTOD.lic
@set INI=%JCHOME%\Server\Config\jfserver.ini
@set d=%DATE%
@set t=%TIME%
@set JCSTARTTIME=%d:~10,4%%d:~4,2%%d:~7,2%%t:~0,2%%t:~3,2%%t:~6,2%%t:~9,2%
call %JCHOME%\jasper\setenv.bat
@echo ..............................................................
@echo Starting JobController at %d% %t%
@echo ..............................................................
@cd %JCHOME%\Bin
@rem -DJC_VERBOSITY=255
@java -DJetTracLF=%JCLICENSE% -jar JobController.jar %INI%
Pause

There are two additional steps to complete the configuration of JetTrac JobController. The first is to set up the JFServer.ini file. The second is to set up the tasks and job steps in the Job Management Database (jfserver.jmd) in JetTrac JobController™.

Configuring the JetTrac JobController ini file:

There is one ini file for JetTrac JobController named JFServer.ini

Sample jfserver.ini:

[Required]
PauseTime=5
FileSpec=*.pdf:PDFJOB|*.xml:*
DataPath=c:\JetTrac\JobController\Server\Data
BackupPath=c:\JetTrac\JobController\Server\Archive
ErrorPath=c:\JetTrac\JobController\Server\Error
LogFile=c:\JetTrac\JobController\Server\Log\JobController.log
BinPath=c:\JetTrac\JobController\Bin
JMDFileName=c:\JetTrac\JobController\Server\Config\jfserver.jmd
JasperPath=c:\JetTrac\JobController\Jasper
ErrorJobName=JBCError
 
[UserVars]
LicenseFile=c:\JetTrac\JobController\License\JTField Service.lic
FormPath=c:\JetTrac\JobController\Server\Forms
PdfPath=c:\JetTrac\JobController\Server\PDF
JasperPath=c:\JetTrac\JobController\Jasper ← No longer used
CmdExe=C:\Windows\System32\CMD.EXE

The following entries are REQUIRED for proper operation.

  • PauseTime = Number of Seconds to delay before recycling through the job steps.
  • FileSpec = Indicate file types/extensions that JTField Service modules can accept. Note: Filetype.extension : Field Service job Type. The “|” character is a delimiter
  • DataPath = A directory where JobController will be “watching”
  • BackupPath = Used to indicate where archives and backup copies are located
  • ErrorPath = Used to indicate where the original data files and associated error logs are deposited. If a job errors it will move the data file and the portion of the log file pertaining to the transaction that threw an error to this folder.
  • LogFile = Fully Qualified Name of the log file.
  • BinPath = Points to a full qualified location where the actual program files are located
  • JMDFileName = the fully qualified name of the Job Management Database File (.jmd)
  • JasperPath = Fully qualified path of the Jasper modules (no longer required for JobController operation)

The following entries are OPTIONAL.

  • ErrorJobname = name of job in the Job Management Database that will be run automatically if a job errors.

The following are entries that refer to the environment and are required when using modules associated to the variable.
LicenseFile = Fully qualified name of the license file for your installation
FormPath = Fully qualified name indicating where any templates and forms are stored
PdfPath = Pully qualified path indicating where PDF forms are saved when a save is requested
JasperPath = Fully qualified path of the Jasper modules required for JobController operation – no longer requred
CmdExe = Fully qualified name of the system executable for a windows command prompt

The JetTrac JobController Command Line:

JetTrac JobController is a Java program and must be run from within the Java Runtime Environment. Refer to Installing Java 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 –DJetTracLF={path to JobController.lic file} -jar {Fully qualified JTJobController.jar file} {Fully qualified JFServer.ini file}

Note: Where no path is provided it is assumed that the file is in the same location as the command file is executed.
Note: We recommend using double quotes (“) around the fully qualified names’s provided. They are not required when no spaces exist in the path. But, where there is a space in path name the quotes MUST be provided.

SAMPLE JobController command line:

java -DJETTRACLF="C:\JetTrac\JobController\License\JTField Service.lic" -jar “C:\JetTrac\JobController\bin\JobController.jar” "C:\JetTrac\JobController\Server\Config\jfserver.ini"

OPTIONAL JobController command line using User Variables:

java -DJETTRACLF=%JCHOME%\License\JTOD.lic -jar %JCHOME%\bin\JobController.jar %JCHOME%\Server\Config\jfserver.ini"

where %JCHOME% has been set in the startServer.bat process.

Running JobController as a service:

To install JobController as a service follow these steps (Assumption: JetTrac Field Service is installed to C:\JetTrac):

  • At a MS-DOS command prompt(running CMD.EXE), type the following command:
C:\JetTrac\Jobcontroller\bin\INSTSRV.EXE JetTracJobController C:\JetTrac\JobController\bin\SRVANY.EXE
  • Run Registry Editor (Regedt32.exe) and locate the following subkey:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\JetTracJobController
  • From the Edit menu, click Add Key. Type the following and click OK:
Key Name: Parameters
Class : <leave blank>
  • Select the Parameters key.
  • From the Edit menu, click Add Value. Type the following and click OK:
Value Name: Application
Data Type : REG_SZ
String : C:\JetTrac\JobController\startServer.bat
* Close Registry Editor.
* Run the services applet from Control Panel (services.msc) and start the newly created service.

 

The JetTrac JobController License File:

As with all JetTrac products, JetTrac JobController is protected from piracy by the JetTrac License Manager system. This system locks JetTrac JobController for use exclusively to one server or system in your organization. It works in this manner:

  • Run JetTrac SiteCode ( “C:\JetTrac\JetTracSiteCode.exe”) on your computer and generate a unique site code file (SiteCode.txt) for your system.
  • You send that site code file to ProTechnology (Email: support@protechinc.com).
  • ProTechnology uses your site code file to generate a product license key file.
  • Pro Technology sends the product license key file (jettrac.lic) back to you.
  • When you receive the license key file, you will copy that file to the C:\JetTrac\JobController\License folder.
  • When JetTrac JobController 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 JetTrac Java and Licensing for further information.

 

Configuring the Job Management Database:

In order to execute jobs using JetTrac JobController is it necessary to create and set up a Job Management Database (JMD). The JMD consists of a file similar to a batch file but contains scripting especially created for the JetTrac JobController system. The Job Management Database now has a graphical front-end called JetTrac JobConfig. Please contact ProTechnology for more information. The default file name for the Job Management Database is jfserver.jmd and is located in “C:\JetTrac\JobController\Server\Config\jfserver.jmd”.

Configuring Jobs in the Job Management Database file:

A Job is a name assigned to one or more command line sequences to be completed by Field Service. A Job Step is ONE line of the set of command lines associated to a job. A Job Step executes or calls a Task passing parameters by reference as needed to complete a set of instructions. Each Task has a unique task name and each task may be used on one or more Job Steps. Each Job may may require multiple steps to complete a job. Each Job Step may call only 1 task.

Example Structure:

JobName1
JobStep1 executes Task1
JobStep2 executes Task2
.
.
JobStepN executes TaskN
.
.
JobNameN
Task1
Task2
.
.
TaskN

 

Top Level JOB processing variables:

Jobs in JetTrac Field Service can be modified by using temporary variables. These variables provide for generating many results from a single job control file and /or job step.

Job Command Line variables:

  • Variables A,B,C,D,…,X,Y,Z – indicate temporary files, these variables map to temporary files as shown:
jbc.temp_A, jbc.temp_B, ... , jbc.temp_Z

At the end of a job, these temporary files are all deleted – the lifetime of each file is the duration of a job.

  • OtherJobTokens – taken from job card
  • PhysicalDevFromJobCard – taken from job card
  • InFile – indicates the input file name that triggered the job to be executed – FQN – Fully Qualified Name
  • DataFile – same as InFile
  • DataName – the bare InFile file name without path or extension

Job STEP command line variables:

  • JOBNAME – name of job executing – from each job step
  • PRINTER – name of printer – from job step
  • MDFName
  • PreambleName
  • MACRONUMBER
  • LOADFLAG
  • PhysicalDev
  • TASKID
  • InFile – may be changed if job step is not *
  • OutFile – may be change if job step is not *
  • STOPONERRORFLAG

A detailed example JMD file with explanation:

# The “#” character indicates a comment line.
# The processor does not read or process lines with leading comment characters
# The “ !F” is a special form of a control-flow statement and is interpreted as an IF statement.
# where the !F <jobname> construct evaluates to true, the Job Step will be fully evaluated/executed,
# calling any Job Tasks (!X) specified.
# The “!X” identifies a Job Task command sequence.
# Job Steps are evaluated sequentially. Meaning JobStep1 is fully executed before JobStep2 is evaluated.
# Sample Job Step command line format
# Every position is required in the Job Step line. If no value is needed, you must specify a placeholder of “*”
# !f <Job name> <Printer name> <Form file> <Preamble file> <Macro number> <Load flag> <Task id> <Input file> <Output file> <On error> <Comments>
# Passing/using substitution variables used in job tasks
# A variable is identified by the leading “@” character followed by a recognized parameter identifier.
# Only @variables shown below may be utilized
# @DataPath - indicates the PATH of the original data-file picked up from the watch-folder.
# @DataName takes the base file name (no path, no extension) of the file from the watch-folder
# @InFile - FQN of the file picked from the watch folder
# @OutFile - Single Letter file name beginning with the letter "A"; they're clean up automatically upon job completion.
# @MDFName - Typically used for a form template used to merge data into but can be used for holding any other information that can be passed from the job step to the task
# @PreambleName - A variable that can be used for holding any information from the job step to the task
# @PhysicalDev - A variable that can be used for holding any information from the job step to the task
# @JobName - The name of the job that is being executed; this variable can be used in the task for multiple purposes
# EXAMPLE Set of Job Steps; note there are 2 jobs with 3 and 2 Job Tasks respectively. There are 5 Job Tasks being called.
 
!f BeneficiaryInfo * "C:\Field ServiceDemo\Forms\BeneficiaryInfo\BeneficiaryInfo_config.xml" * * * PDFExtract * A C
!f BeneficiaryInfo * "C:\Field ServiceDemo\Forms\BeneficiaryInfo\BeneficiaryInfo_config.xml" * * * JTDBUpdate * A C
!f BeneficiaryInfo * "C:\Field ServiceDemo\Forms\BeneficiaryInfo\BeneficiaryInfo_JTEmail.ini" * * * JTEMAIL * A C
!f MatrixIntake * "C:\Field ServiceDemo\Forms\Matrix\MatrixIntake\MatrixIntake_XFAFormTemplate.pdf" * * * PDFMerge * * C
!f MatrixIntake * "C:\Field ServiceDemo\Forms\Matrix\MatrixIntake\MatrixIntake_FBUpload.ini" * * * JTFBUpload * * C
 
# The last job is included for those circumstances where there is no specified Job_Name in the operation
!f NOJOB * C:\Field ServiceDemo\JobController\JTJobCard\JTJobCard.ini * 1 y NOJOB * * * *
!f PDFJOB * * * * * PDFJOBID * A C
 
# Task table
# !x <Task id> <[This column reserved]> <Program name> <Program options> <Comments>
# The format of the Job Tasks is dictated by each modules parameter requirements
# <[This column reserved]> is always specified as an asterisk *
#<Program Name> is always surrounded by double quotes: ”<Program Name>”
# <Program options> are delimited with double-double quotes: ””<parameter>””
# Variable substitution on a job task is executed when the @Variable form is followed by a period.
# eg. @InFile. will substitute the value of @InFile in the current position.
# Each task is executed and returns to caller
 
!x JTDATAPREP * java " -jar -DJETTRACLF=""C:\Field ServiceDemo\JobController\License\JTOD.lic"" ""C:\Field ServiceDemo\Programs\JTDataPrep\JTDataPrep.jar"" ""@InFile."" ""@OutFile."" ""C:\Field ServiceDemo\Forms\Matrix\Matrix_JTDataPrep.ini"" ""@LogFile.""" "Changes Job Name"
!x JTDBUpdate * "C:\Field ServiceDemo\Programs\JTDBUpdate\DbUpdateFromXml.exe" """@InFile..txt"" ""@MDFName."" ""@LogFile.""" "Inserts new record into database"
!x JTDBUpd1 * "C:\Field ServiceDemo\Programs\JTDBUpdate\DbUpdateFromXml.exe" """@InFile."" ""@MDFName."" ""@LogFile.""" "Inserts new record into database"
!x JTEMAIL * java " -jar -DJETTRACLF=""C:\Field ServiceDemo\JobController\License\JTOD.lic"" ""C:\Field ServiceDemo\Programs\JTEmail\JTEmail.jar"" ""@InFile..txt"" ""C:\Field ServiceDemo\Forms\BeneficiaryInfo\Output\Confirmation.pdf"" ""@MDFName."" ""@LogFile.""" "Sends email"
!x JTEMLQB * java " -jar -DJETTRACLF=""C:\Field ServiceDemo\JobController\License\JTOD.lic"" ""C:\Field ServiceDemo\Programs\JTEmail\JTEmail.jar"" ""@InFile."" ""C:\Field ServiceDemo\Forms\QBWkOrdr\ToField\@DataName._Output.pdf"" ""@MDFName."" ""@LogFile.""" "Sends email"
!x JTEMLQB2 * java " -jar -DJETTRACLF=""C:\Field ServiceDemo\JobController\License\JTOD.lic"" ""C:\Field ServiceDemo\Programs\JTEmail\JTEmail.jar"" ""@InFile."" ""@PreambleName."" ""@MDFName."" ""@LogFile.""" "Sends email"
!x JTFBUpload * "C:\Field ServiceDemo\Programs\JTFBUpload\FbUpload2.exe" """@InFile."" ""c:\Field ServiceDemo\JobController\Server\Data\Test\@DataName._Output.pdf"" ""@MDFName."" ""@LogFile.""" "Runs JetTrac FileBound Upload"
!x NOJOB * "java ""-DJETTRACLF=@LicenceFile."" -jar ""C:\Field ServiceDemo\JobController\JTJobCard\JTJobCard.jar""" """@InFile."" ""C:\Field ServiceDemo\JobController\Server\Data\@DataName."" ""@MDFName."" ""@LogFile.""" "add job card"
!x PDFExtract * "C:\Field ServiceDemo\Programs\JTPDFExtract\PdfExtract.exe" """@InFile."" ""@InFile..txt"" ""@MDFName."" ""@LogFile."" ""EXTRACT""" "Runs JetTrac PDFExtract in Mode EXTRACT or JOBID"
!x PDFExtqb * "C:\Field ServiceDemo\Programs\JTPDFExtract\PdfExtract.exe" """@InFile."" ""@OutFile."" ""@MDFName."" ""@LogFile."" ""EXTRACT""" "Runs JetTrac PDFExtract in Mode EXTRACT or JOBID"
!x PDFJOBID * "C:\Field ServiceDemo\Programs\JTPDFExtract\PdfExtract.exe" """@InFile."" ""@DataPath.\@DataName._job.xml"" ""C:\Field ServiceDemo\Forms\Matrix\Matrix_config.xml"" ""@LogFile."" ""JOBID""" "PDFJOBID job"
!x PDFMerge * "C:\Field ServiceDemo\Programs\JTPDFMerge\PdfFiller.exe" """@InFile."" ""c:\Field ServiceDemo\JobController\Server\Data\Test\@DataName._Output.pdf"" ""@MDFName."" ""@LogFile.""" "Runs JetTrac PDFMerge"
!x PDFMrgqb * "C:\Field ServiceDemo\Programs\JTPDFMerge\PdfFiller.exe" """@InFile."" ""C:\Field ServiceDemo\Forms\QBWkOrdr\@PreambleName.\@DataName._Output.pdf"" ""@MDFName."" ""@LogFile.""" "Runs JetTrac PDFMerge"

Issues to consider when implementing JetTrac JobController:

  • Do you have access to an SMTP server from where JetTrac JobController is running?
  • Do you have a batch of documents? If so, do you want to create a PDF file for each document so they can be ‘JobControllered’ out individually? If so you may need JetTrac Route to split them out for you.
  • In your batch of documents do you have some that need to be printed, fax or JobControllered? How can we tell which need to be JobControllered? JetTrac Route does this functionality.
  • Where will you get the JobController addresses? If they are not output of your host system, then JetTrac Lookup can be used to lookup the JobController address based on a key value like Vendor Number, Customer Number, etc.
  • Do you want to attach a PDF file to the JobController or do you want to have all information in the body of the JobController?
  • If you don’t need to attach a PDF file, do you have multiple customers to send messages to in one batch?
  • If you want to have nicely formatted messages as the body, you need to have an HTML file to use as the body of your JobController.
  • If you want to dynamically pass a body or subject line, you can do it within the INI file. Instead of only hard-coding in the body or the subject, you may specify the ASCII file. Within the ASCII file, you may use variable data fields, so that each JobController changes with each person, who receives it.

 

Version Changes:

Version 4.6 supports a [GlobalVars] section in the JobController INI file. 

The variables in this section will be available for substitution when a job is run.

[GlobalVars]
LicenceFile=C:\JetTrac\JobController\License\jclic.dat
FormPath=C:\JetTrac\JobController\Server\Forms
PdfPath=C:\JetTrac\JobController\Server\PDF
CmdExe=C:\Windows\System32\CMD.EXE
CompanyName=Flintstone Inc.
ErrorEmail=**bambam@flintstone.com**

[TimedJobs]
RunEvery=3600-HOURLY
RunDaily=22-TENPM
RunWeekly=1-SUNDAY
RunMonthly=1-MONTHLY

With this in the INI file, you can use the [GlobalVars] as substitution variables when running a job.

For example in the JMD you can have something like this:

!x JBCMSG * JBC.LOG “””@ErrorEmail.”” “”@CompanyName.”””

There are also some automatic substitution variables that you can use to create time-tagged file names:

JobTimeYear 2015
JobTimeMonth 04
JobTimeDay 15
JobTimeHour 23
JobTimeMin 59
JobTimeSec 09

For example: in the JMD you can have:

!x JBCMSG * JBC.LOG “””@ErrorEmail. @CompanyName. @JobTimeYear.-@JobTimeMonth.-@JobTimeDay. @JobTimeHour.:@JobTimeMin.:@JobTimeSec.”” “”@CompanyName.”””

And you will get:

After substitutions : JBC.LOG “bambam@flintstone.comFlintstone Inc.
2015-08-24 21:28:14″ “Flintstone Inc.”

FileDelete & FileCopy:

There are two additional modules that can be added to the jfserver.jmd file that are useful for troubleshooting issues and performing minor functions. These are:

FileDelete

  • Will delete files during the job step that calls this module.
!f JobName DEFAULT * * * * FileDelete * * S " "
!x FileDelete * "JBC.DELETE" """@UDV1."""

FileCopy

  • Will copy a file to a specified file path. In the following example “C:\somewhere\FileToBeCopied.pdf” would be replaced with the file you wish to make a copy of and “C:\somewhere\NewFileName.pdf” would be the file path and name for the new copy you are creating.
!f JobName DEFAULT "C:\somewhere\FileToBeCopied.pdf" "C:\somewhere\NewFileName.pdf" * * FileCopy * * S " "
!x FileCopy * "JBC.COPY" """@MDFName."" ""@PreambleName.""