The following is a guide to the file format and the process necessary to begin sending us POD and shipment disposition data via email.
The file is in CSV format except that line breaks inside fields are forbidden. Many companies won't have data for all of the fields in the format, so just use null values for the fields you're not using. Null values are represented as two adjacent commas, or as a comma followed by end of line (or preceded by beginning of line, but that can't happen with this format). A null value is not the same thing as "", which is the empty string.
The character encoding is ISO 8859-1 (eg, n~ is character 241, e' is character 233). The fields present depend on the first field, the format version. Each version includes the fields in earlier versions and adds some. The first column in the File Format lists the first version in which a field is present.
format_version int 1, 2 or 3
sender_key int numeric key from the file we send you
receiver_key int numeric key from your database, if you have one
ibc_awb char 11 IBC's HAWB, required unless
vend_ref_num or full_awb is supplied
ship_ref_num char 11 the customer's reference #
3 full_awb char 40 shipper's full HAWB
2 vend_ref_num char 22 the HAWB/tracking number you deliver on
creation_date date YYYYMMDD the date you received the shipment
origin char 3 the three letter city code
final_dest char 3 the three letter city code
outlying char 1 X for outlying cities, null otherwise
disp_code_date date YYYYMMDD
disp_code_time time HHMM
disp_code char 2 see below
pod_date date YYYYMMDD
pod_time time HHMM
pod_name char 25
The remaining fields can be repeated any number of times (including 0):
comment_text char 511 Text of the comment
comment_date date YYYYMMDD
comment_user_login char 8 The username of the commenter
comment_user_station char 3 The station of the commenter
comment_full_name char 30 The full name of the commenter
The disp code (disposition code) fields are used to provide updates before the shipment is delivered. Our codes must be used; for a complete list of codes and their meanings see our disposition code list.
Furthermore, the three disposition code fields must either be all present or all null.
The same applies to the three POD fields -- a record must contain either three good values, or three null entries.
For the comment fields, they, too, must be treated as a group of 5 fields. However, if you have no comments, you do not need to include 5 nulls; you can just exclude the fields entirely. Also, you can have more than one comment per record, by repeating the fields (all 5) in the same record, as many times as you need.
Other than the comment fields, though, all fields must be present in each record in the file, even if left null. The bare minimum you must send in order to send us a POD in a valid record would be to fill in the following fields
You can download these examples, minus the commentary, in the file pods-to-pactrak-sample.csv.
Here are some "bare minimum" PODs (i.e. just the required fields are filled in, the rest are null):
2,,,123456780,,,,,,,,,,20071126,0925,TOM SMITH 2,,,123456781,,,,,,,,,,20071127,1437,TOM JONES 2,,,123456782,,,,,,,,,,20071203,1022,RECEPTION 2,,,123456783,,,,,,,,,,20071204,1205,COMPANY STAMP 2,,,123456784,,,,,,,,,,20071203,0912,GEORGE BUSH 2,,,123456785,,,,,,,,,,20071204,0945,MARY SMITH 2,,,123456786,,,,,,,,,,20071205,1000,BOB KING 2,,,123456787,,,,,,,,,,20071203,1030,MAIL ROOM 2,,,123456788,,,,,,,,,,20071203,0955,SUSAN SMITH 2,,,123456789,,,,,,,,,,20071203,0905,ROBERT GONZALEZ
Here are some "bare minimum" records with disposition codes:
2,,,123456780,,,,,,,20071126,1435,ND,,, 2,,,123456781,,,,,,,20071124,1020,BA,,, 2,,,123456782,,,,,,,20071204,0900,AD,,, 2,,,123456783,,,,,,,20071128,0845,NK,,,
Here are some entries (PODs and Disp. Codes) with comments
2,,,123456781,,,,,,,,,,20071127,1437,TOM JONES 2,,,123456782,,,,,,,,,,20071203,1022,RECEPTION,SHE WOULD NOT SIGN,20071204,rking,GVA,ROBERT KING 2,,,123456783,,,,,,,20071121,0845,NK,,,,"They don't know any named Smith. Please advise new name, if available",20071204,,,
Lastly, here is a POD record with more of the other fields filled in:
2,,,123456780,55121A,,20071123,LHR,GVA,X,,,,20071126,0925,TOM SMITH
You'll send the data to us via email. You can send it as a plain (non-MIME) message, or as a single-part MIME message. Multi-part MIME messages can't be used.
Your data messages must contain only formatted shipment updates. It shouldn't contain explanatory text, a signature, an anti-virus message, or any other information in the body.
When you're ready to start testing you can send data to pod-test-auto@pactrak.com. Our system will do basic syntax validation of the data and send you a message back noting that the file looks okay or detailing the errors. We suggest you send a large, representative sample of the data you'll be providing us, not just a few records.
When the automated testing consistently reports no errors with your data, please send a (large, representative) sample to pod-test@pactrak.com. This message will be reviewed by a human, primarily to inspect it for more subtle problems.
Once we have manually reviewed your data we will provide you with a special email address to send the files for automated processing. Each of those email addresses is vendor-specific so that we can tell where the data is coming from easily.
We'll note again that live data must be sent in an email which is either not a MIME message or a single-part MIME message. Live data cannot be sent in a multi-part MIME message. If you have difficulty with the email transmission, see Sending Data to IBC.
Many customers have trouble sending data to IBC in the way that IBC requires -- either as non-MIME (simple text) email or single-part MIME messages.
You can test your ability to send the data as a single part message by sending a test message to yourself. Look at the full headers of the message you receive. (For example, in Thunderbird select View then Message Source.) If there is a "Content-Type" header and the value starts with "multipart" then it won't work. There should either be no Content-Type header, or if there is one the value has to start with something other then multipart (for example, "text/plain" or "text/csv").
Some customers are able to send one of these types, but the email program line-wraps the data in the file (which will cause failures), or a virus-scanner adds a message to the email which makes the data invalid.
As a way to send the message to us without either of these issues we have located a piece of free software that will help customers running in a Windows environment transmit their data files to IBC. The program is called wmailto, and you can read more about it here. You can also download the file from our server with this link wmailto.zip and you should extract the exe from the zip file, and put it on the computer that is sending us the data files.
Run it the first time with the following command:
wmailto -init
and fill in the mail server address, the from address (anything valid)
and then you can skip the remaining questions by just hitting return.
That sets up the program.
Then, when you are ready to send us the test file, use the following
command
wmailto -stest -tFILENAME pod-test-auto@pactrak.com
where FILENAME is the manifest file you want to send.
Of course, if it is not in the same directory that you are working
in, then be sure to include the full path. If you want to cc: yourself
use the -c option like this:
wmailto -stest -tFILENAME -cme@abc.com pod-test-auto@pactrak.com
where you change the me@abc.com to be the address you wish to cc.
Some customers prefer using a graphical application to send the email. While we have not personally had experience with it, some of our customers have successfully used Blat in place of wmailto.
It is important that you use the same software to send the test files as you will use in live production. We have had numerous cases where the test files looked good, and only when the live files were transferred did we see that the email messages were not being sent properly.