Job Elements

Generating an output file or form using TrueAddress (TA) requires the following components:

Registered TA software that includes an XML schema definition (XSD) file and an XML configuration file (usually static).
A List or Name file (referred to as input in this guide).
Current data for CASS, NCOA data (if using NCOA), and the most current EWS file (if using EWS).

You are required to update the CASS data monthly. If using EWS, the EWS file must be updated weekly. For instructions on how to perform the on-going data updates, refer to Updating CASS & EWS Data in theTrueAddress®(TA) OnPrem - Linux Installation Guide and Updating CASS, EWS & NCOA in theTrueAddress®(TA) OnPrem - Windows Installation Guide. Updating the NCOA data is the responsibility of the Client, but we provide a basic list of what you need to do, for Linux installation guide, see Updating NCOA Data.

A job XML file containing basic run configuration and information, and Input and Output file definitions and formats.

XML Schema Definition (XSD) File

The creation of the various XML files for use with TA is the responsibility of the Client; however, the XML files must conform to the “TrueAddress.xsd” schema file. An XML Schema Definition or XSD file is used to describe and validate the structure and content of XML data. The schema defines the elements, attributes, and data types. The basic idea behind XML schemas is that they describe the legitimate format that an XML document can take. The “TrueAddress.xsd” schema file uses standard values (some of which are required) and can also include values defined by the user.

There are many references describing XML schema files, and it is beyond the scope of this document to duplicate these. Any errors in basic XML syntax or conformation to the schema are explicitly detailed in an error message, so tracking down errors should usually be straightforward.

Refer to XML File Components for general information about XML files and XSD schema files.

The ‘TrueAddress.xsd’ schema file is automatically created during the installation of TA based on information entered by the user and is located in the ‘TrueAddress’ directory.

Linux System

The contents of the schema file will vary depending on whether “NCOA” is selected during the installation of TA, and the appropriate registration is completed.

XML Configuration File

With the exception of the XML configuration file, which is created automatically at the time of installation, the creation of the various XML files for use with TA is the responsibility of the Client. All TrueAddress-related XML files; however, must conform to the “TrueAddress.xsd” schema file. Refer to XML Schema Definition for more information.

TA also automatically creates a configuration XML file based on the information entered during installation. This configuration XML file resides in the ‘TrueAddress’ directory and is named “TrueAddress_config.xml”. This is the default location and file created during the installation. You can change the location and or name; however, Window Book recommends using the defaults provided.

Linux System

Refer to XML File Components for general information about XML files.

The configuration file is referenced with every batch command run. It identifies the various data paths and the optional EWS file path. In addition, if the NCOA option is installed, NCOA Log and Reports paths are also identified. The configuration file also contains the list processor information, which displays on the USPS Form 3553.

Job XML Files

The job XML file defines the basic run configuration and information, and also the input and output file formats. Job XML files can be built using the fields available in TA, which are documented in this Guide (refer to Available Job Level Fields; Available Address Matching Fields; and Available NCOA Fields). Any Client-preferred XML editor or even plain text editor can be used to create these files. Most browsers will display XML nicely and check syntax.

In addition, the installation of TA includes example files that can be used as templates instead of writing/creating files from scratch (refer to CASS Example Files for more information).

Below is a list of the necessary structural components required for creating a basic job XML file to be used with TA. Job XML files can be more complex, especially when the output involves PDF forms.

Refer to XML File Components for general information about XML files.

Run Configuration & Information

Run configuration and information must be present in each job XML file. It consists of the:

Job_Name
Job_ID
CASS_Options, which consist of the:
List_Name
Mailer information (name, address, phone, and contact name)
Output_Casing (for example, Mixed).
NCOA_options (if the NCOA feature is installed), which consists of the:
PAF owner and license information
BALA_PAF information (broker agent or list administrator)
Match_Mode (for example, “S”)
Mail_Class (for example, “O”)
Processing_Category (for example, “STAGE II”)
Max_Month_Range

Refer to NCOA Job XML files in this Guide for more information on the available NCOA match/processing modes.

In addition, the number of threads may also be specified (the default is 1, the maximum allowed is 127). Depending on the server or computer TA is being run on, the larger the number of threads used, the faster the job will run. Before specifying a thread number; however, take into consideration the size and capability of the computer or server being used. The higher the thread number, the more robust the computer or server needs to be in order to achieve faster performance by TA when running large jobs.

Input & Output File Formats

In addition to the basic run configuration and information, the job XML file needs to have both an Input and an Output section.

Input

The Input section of the job XML file defines the setup of the List or Name/Address file, so TA knows what it is looking for and where, when creating the output file. The information required for the Input section is as follows:

Whether the input file contains a header row must be specified (“true” or “false”).
The Record_Type is “Input”.
The location (directory name) and file name of the input file must be specified (for example, “Input/stg2.lst”).
The format type (labeled as File_Format) of the input file must be specified. Only fixed and delimited formats are allowed for input files.

A File_Format of fixed requires the inclusion of overall record length of the file -

(<…File_Format=”Fixed” Record_Length>”299”>), as well as a corresponding length for each individual field (for example, <Field Length=”50” Column=”30” Name=”Full_Name”/>)

If the File_Format is “Delimited”, the delimiter being used must also be specified (for example, pipe “|”). In addition, each field name must be identified and be associated with the corresponding column number in the file, for example <…Field Column=”1” Name=”Full_Name”/>.

Any name may be specified for a field in the input file. However, field names listed in the Address Matching/Input Variables section (for more information go to Available Address Matching Fields these fields have special meaning and are for CASS processing. Other names are available for mapping to output files.

Output

The Output section of the job XML file is used to define the format for the output file, and to identify and define the fields that are to be included in the output file when the job is run.

The information required for the Output section is as follows:

Whether the input file contains a header row must be specified (“true” or “false”).
The Output section requires at least one Output_File_Record_Type. An Output_File_Record_Type defines which fields are available when the job is run (for available fields, refer to Available Address Matching Fields). There are two Output_File_Record_Types – “Job Start” and “Job End”.

”Job_Start” - (not required) typically used for logging. In addition, these need to be defined:

File_Format is required.
Form_File is the location and name of the form file being used (for example, “Forms/Example_Celeb_HTML_start.form”.
File_Name is the location and output file name (for example, “Output/Example_Celeb_html”.

Output_File_Record_Type - (required) – refer to the information/screen examples provided for File_Format of “Job End” below:

”Job_End” – only required for creation of forms (e.g. PS Form 3553). In addition, these need to be defined:

File_Format is “PDF”.
Form_File is the location and the name of the form file to be used (for example, “Forms/create3553.form”).
A “File_Name” (the location (directory name) and output file name (for example, “Ouput/NCOA_stg2_3553.pdf”)).

A File_Format for the output file. The output File_Format can be Fixed, Delimited, or Text (the most typical or common being Fixed and Delimited).

If the file format is Delimited, the delimiter being used must also be specified (for example, pipe “|” or comma “,”). In addition, each field name must be identified and be associated with a column number in the file, for example <…Field Column=”1” Name=”Full_Name”/>.

A fixed File_Format requires the inclusion of overall record length of the file (for example, <…File_Format=”Fixed” Record_Length>”200”>), as well as a corresponding length for each individual field (for example, <Field Length=”200” Column=”1” Name=””rec”/>)

The more complex File_Format type of “text” equates to a sort of free form. There are no defined fields in the Output section of the job XML file. Fields are embedded in a text file(s) that is called out in the Output section of the job XML.

Users can refer to their ‘WB\TrueAddress\XML’ directory for examples of XML files.