The following document will go through the functionality found within JetTrac Email. This module is used to send an email automatically with the option to add an attachment. This module is typically also used as the transport mechanism to start another job. To do this you can set the module to send an email with an attachment to an email address being watched by POP3Scanner which will then download the attachment and drop it into your JetTrac watched folder.
Please note that any files edited while setting up JetTrac Email should be edited using Notepad or Notepad++. Do not use Microsoft Word or Wordpad as these text editors will add formatting that will interfere with the program reading the files.
If you need assistance in installing and configuring JetTrac Email™, call Pro Technology Automation, Inc. at 805-527-1248 or email us at firstname.lastname@example.org. Please note that the JetTrac Email™ 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.
To run the program, you will need to have the following files located in the same folder:
The JTEmail.jar file is required for the program to run and should never be edited.
JetTrac Email uses a configured SMTP email server to send an email that can contain an attached file.
When setting up a job step using JTEmail in JobConfig the only lines of the config you need to worry about are the Config file, the Attachment, and the Input 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 file. Eg: C:\JetTrac\…\input.xml The Attachment line is optional as the email attachment can also be designated in the Config file.
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 command line for JetTrac Email is as follows:
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.
java -jar -DJETTRACLF=”C:\JetTrac\JobController\License\jettrac.lic” C:\JTEmail.jar “C:\Input.xml” “C:\Attachment.pdf” “C:\Config.ini” “C:\JTEmail.log”
In this we are referencing the license file, the .jar for the module, the input XML data, the file path to the attachment to the email, the configuration file used to set up the module’s specific functionality, and the log file.
The attachment part of the command line will be different depending on if you want to specify it on the command line, within the configuration .ini file, or do not wish to have an attachment at all. If you do not want to specify the attachment on the command line or do not want to have an attachment at all, replace this with “NA”. A command line without the attachment would look like the following:
java -jar -DJETTRACLF=”C:\JetTrac\JobController\License\jettrac.lic” C:\JTEmail.jar “C:\Input.xml” NA “C:\Config.ini” “C:\JTEmail.log”
The following is a sample configuration .ini file used when running JetTrac Email:
|1||#To Email <email@example.com>|
|2||#CC Email <firstname.lastname@example.org>|
|3||#BCC Email <email@example.com>|
|4||#This is a test of JetTrac Email|
|5||#From Email <firstname.lastname@example.org>|
|6||#This is a test email body.|
This configuration .ini file contains values which set up specific functionality within the module. Unlike other modules, this configuration file is not a key value list. As such, each line is specifically set aside for a different configuration value and must be in this exact order and on these exact lines. Optional values can be left blank; however, the line must still be reserved. NOTE: JTEmail can pull directly from the input XML valiues without using JTSetVariables using the format: “@JetTrac.xmltag”
- 1: This is the name and the email address that you are sending to. You can either enter in a value similar to the sample or if you don’t want to have a display name, just enter the email address itself (without the brackets). This line must begin with a pound sign unless using a variable.
- 2 (optional): This is the CC email address and display name. You can either enter in a value similar to the sample or if you don’t want to have a display name, just enter the email address itself (without the brackets). This line must begin with a pound sign unless using a variable.
- 3 (optional): This is the BCC email address and display name. You can either enter in a value similar to the sample or if you don’t want to have a display name, just enter the email address itself (without the brackets). This line must begin with a pound sign unless using a variable.
- 4: This is the subject line for the email. This line must begin with a pound sign unless using a variable.
- 5: This is the name and the email address that you are sending from. You can either enter in a value similar to the sample or if you don’t want to have a display name, just enter the email address itself (without the brackets). This line must begin with a pound sign unless using a variable. If referencing a field name from an XML, that XML cannot contain a comma. The From email address also cannot contain a tilde.
- 6: This line is used to specify the email body. You can either enter in simple text here or reference an .htm file. This line must begin with a pound sign unless using a variable.
- 7 (optional): This line is used to reference the email attachment you wish to use. This can be used in place of specifying the attachment in the command line or alongside. Specify multiple with carriage return line feed.
- 8: This line is the SMTP server information that you wish to use to send the email. This information contains the server address and port number, username (typically an email address), and password. This can be obtained from your email provider.
- 9: This is the SMTP address domain name. This can also be obtained from your email provider.
- 10 (optional): This line is used when sending batches of emails. Here you enter in the start field within the input XML that contains each email. This will rarely, if ever, be used.
- 11: This line can contain either “Y” or “N” and determines if the module will stop after the first email. This will only ever change if you are sending out email batches using JetTrac Email. Otherwise, leave this set to “Y”.
- 12: This line can contain either “Y” or “N” and determines if the email being sent has an HTML or plain text format for the body.
- 13: This line will contain either a “1” or a “2” depending on if you want a basic or verbose log when this runs. This is useful when troubleshooting errors when running JetTrac Email. Typically this will stay set at “2”.
- 14: This line is another “Y” or “N” setting and determines if the attachment file located on line 7 will be kept or deleted after JetTrac Email sends it. This usually is set to “N”.
- 15: This line will typically never be changed from “comma”. By default email addresses within JetTrac Email are separated by semicolons, however, this can cause issues with some email clients. As such, adding “comma” to this line as opposed to leaving it blank separates multiple email addresses with commas instead.
- If you want to use the following characters in XML that JTEmail reads then these escape characters need to be used in the data:
- To list multiple email addresses in any line, the emails must be semicolon separated with no space.
- If the email address(es) are coming from an XML file and you wish to format them with a user friendly name use the following syntax: ProTechnology Support <email@example.com>