Introduction:
The following document will go through the functionality found within JetTrac XMLTrans. The purpose of this module is to create new fields that concatenate fields within the XML and fixed strings.
Technical Support:
If you need assistance in installing and configuring JetTrac XMLTrans™, call Pro Technology Automation, Inc. at 805-527-1248 or email us at support@protechinc.com. Please note that the JetTrac XMLTrans™ 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 XMLTrans:
To run the program, you will need to have the following files:
- JTXMLTrans.exe
- ExitHandler.dll
- Config.xml
Executable files and dll files should not be edited for any reason.
Default Functionality:
JetTrac XMLTrans takes an input XML data file and a configuration XML file. Then depending on what configuration is found within the configuration XML file for JetTrac XMLTrans, it will make the changes and output a new XML file.
Job Step Configuration Window in JobConfig for JetTrac XMLTrans:
When setting up a job step using JTXMLTrans 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 you want to edit. All other fields should be filled with the fully qualified path to the intended file. Eg: C:\JetTrac\…\input.xml
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 XMLTrans Command Line:
The command line to run JetTrac XMLTrans contains the location of the .exe file, the input XML file, the location to save the modified output XML file, the location of a configuration XML file, and the log file. The following is an example of the command line used to run this module:
“C:\JTXMLTrans.exe” “C:\Input.xml” “C:\Output.xml” “C:\Config.xml” “C:\JTXMLTrans.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.
JetTrac DataPrep Configuration .ini:
Unlike the majority of our modules, JetTrac XMLTrans does not use a configuration .ini file. Instead, this module uses an XML configuration file (similar to POP3Scanner). Within this file you will need to have a section specifically for JetTrac XMLTrans. The following is an example of the section in the configuration file:
<Config>
<Configure_JetTrac_XMLTrans>
<RemoveNullFields>N</RemoveNullFields>
<RemoveFieldsByValue>Off</RemoveFieldsByValue>
<CreateField>
<FieldName>OutputFieldName</FieldName>
<Term>Field1</Term>
<Term>” Static String 1 “</Term>
<Term>Field2</Term>
<Term>” Static String 2 “</Term>
</CreateField>
<CreateField operation=”*”>
<FieldName>Result</FieldName>
<Term>TermA</Term>
<Term>TermB</Term>
</CreateField>
<CreateField extract=”4,2”>
<FieldName>DateMonth</FieldName>
<Term>Date</Term>
</CreateField>
<CreateField>
<FieldName>TimeOutput</FieldName>
<Term>$AMPM(TimeInput)</Term>
</CreateField>
<CreateField>
<FieldName>DateFormatted</FieldName>
<Term>$DATE-YYYYMMDD</Term>
</CreateField>
<CreateField>
<FieldName>TimeFormatted</FieldName>
<Term>$TIME-HH:MM:SS</Term>
</CreateField>
</Configure_JetTrac_XMLTrans>
</Config>
Each of the sections within the configuration XML file perform a specific function and can be used or left out entirely depending on what functionality. In addition, you can have multiple copies of the same functionality if you need to run it multiple times. In this way JetTrac XMLTrans is very flexible. The following goes through each individual piece of functionality and explains what it does and how to use it:
- RemoveNullFields: This can either be set to “Y” or “N”. If set to “Y” all fields that do not have a value within the XML will be removed. You can only have a single copy of this line in the XML.
- RemoveFieldsByValue: This field will remove any field nodes that have the value entered in here. In the example above, any fields within the input XML that have the value of “off” will be removed entirely from the XML. You can only have a single copy of this line in the XML.
- Concatenation: This create field function includes a “FieldName” value which is the name of the field that will be added to the output XML file with the concatenated value. After the FieldName value, you will need to add two or more lines with a “Term” value that specifies what data will be concatenated to make up the value that will be in the field. In here you can either add a field name or a static string, but static strings will need to be surrounded by double quotes. In the above example the output XML will have a field named “OutputFieldName” with the value of “(Field1) Static String 1 (Field2) Static String 2”. The value will of course replace the field names within the parenthesis with the value for those field names in the input XML. You can have any number of these sections within the XML configuration file.
- Arithmetic: This create field function will create a field in the output XML with the name of whatever you enter into “FieldName” that has the value of the calculation you specify between two fields that you also specify. In this example a field named “Result” will be added to the output XML file with the value of whatever was in the field “TermA” times the value of whatever is in the field “TermB”. On the first line of this section the asterisk in the example refers to multiplication but can also contain a dash “-“ which refers to subtraction, and slash “/” which refers to division, or a plus “+” which refers to addition. You can have any number of these sections within the XML configuration file.
- Extract: This section will extract a part of a field’s value and output it as the value for a new field. On the first line you will notice the “4,2”. This refers to the fourth character in the value and to extract two total characters. The next line, “FieldName”, is the name of the field that will be added to the XML with the extracted value. The last line, “Term”, is the existing field name that you wish to extract the value from. For example, if you have a field within your XML input file with the name “Date” and a value of “20170230”, XMLTrans as set up above will output a new field called “DateMonth” that will have two characters as the value starting after the fourth character of the “Date” field’s value. This means the “DateMonth” field will have the value of “02”. You can have any number of these sections within the XML configuration file.
- Military to Standard Time: This section has the very specific purpose of taking a field with a military time (or 24-hour time) value and converting it to standard time. On the first line in the section “TimeOutput” will be the name of the new field added to the output XML. On the following line, replace “TimeInput” with the field name in the input XML that has the military formatted time value. For example, if “TimeInput” has the value of “1430”, TimeOutput will have the value of “02:30 PM”. You can have any number of these sections within the XML configuration file.
- Date Formatting: This section takes the date value from an input field name and outputs the value formatted as specified in the next line. In this example, it is outputting the field name “DateFormatted” with the value that was found in the input field “Date” and formatting it YYYYMMDD. On the second line you can replace “Date” with whatever the field is named in the input XML and “YYYYMMDD” with the format that you would like. The following are the formats you can choose from:
- o YYYYMMDD
- o MM/DD/YYYY
- o DD/MM/YYYY
- o YYYY-MM-DD
- o MONTH_DD_YYYY
You can have any number of these sections within the XML configuration file.
- Time Formatting: This section functions the same as the Date Formatting section, however, is used with time values to reformat them as you wish. The following are the formats available to you:
- o HHMMSS
- o HH:MM:SS
You can have any number of these sections within the XML configuration file.
Additional Notes:
All of the configuration options within the configuration XML file are optional. If you do not wish to use the function, don’t add it to the configuration file. In addition, with the exception of the global configuration options (RemoveNullFields and RemoveFieldsByValue), all of the configuration sections can be used multiple times in the same configuration XML file.