Shipping Exchange

Third-party shipment-tracking software (e.g. ReadyShipper, Starship, NRGship) can be integrated with AcctVantage by configuring the Shipping Exchange function in System Setup. This article addresses the process from the point of view of AcctVantage. For assistance with installation and use of 3rd party shipping software you should contact your vendor for tech support.

To use UPS Worldship you must obtain a middleware product called Crossware, which is available free of charge from your UPS rep. For FedEx, AcctVantage is part of their "code library" and your rep can download integration code to install at your site. You may also download the complete reference guide on Starship; the detailed appendices are applicable to any third-party shipping product that uses the ADE (automated data exchange) process.

In short, these programs communicate with AcctVantage by passing files back and forth in a folder on the Server computer. A file named ADEOUT is placed in the folder by the shipping software. AcctVantage picks up the ADEOUT file and places a file named ADEIN into the same folder.

Setting up connections

  1. On the AcctVantage Server computer, create a new folder inside the folder AcctVantage ERP/Your Company Data--name it Shipping.
  2. Follow your operating system procedure to make this folder shared on your network.
  3. On the AcctVantage Client computer from which you will track packages, install the shipping software.
  4. Follow your operating system procedure to “map a network drive” or otherwise connect this Client computer to the shared folder Shipping on the Server computer.
  5. Follow the shipping software instructions to point it to the shared Shipping folder on your AcctVantage Server computer.

Configuring shipping exchange

  1. On the AcctVantage Server computer, have all users log off and shut down the AcctVantage Server application.
  2. Launch the AcctVantage Single User application.
  3. Hold down the alt (option) key while opening the Single User application.
  4. Click Select another data file and point to your datafile located in the /Your Company Data folder.
  5. Go to Administration ➤ System Setup.
  6. Select Shipping & XML Import from the drop-down list. Don’t press the Start button yet.
  7. Click the Browse button and navigate to the Shipping folder you created in Step 2 of Setting up Connections.
  8. Enter a value in the seconds field, such as 10 (this is how frequently AcctVantage will check for a file in this folder).
  9. Shut down AcctVantage Single User.
  10. Launch the AcctVantage Server.

Testing communication from the shipping software

  1. Launch the shipping software and enter a package to ship. The Order Number you enter in the shipping software should be equivalent to a Sales Document ID number in AcctVantage. This is NOT what is displayed as “Order Number” on a Sales Order. The Sales Document ID number can be found by clicking on blue information icon located in the lower center area of an open Sales Order record. It is also typically printed on the standard Invoice form in the lower right corner.
  2. Once the package has been shipped in the shipping software, a file named ADEOUT is sent to the Shipping folder on the AcctVantage Server computer. Look in this folder to confirm you see this file. If it is present, all is well. If you don’t see it, you should check your network connections and the path identified in the shipping software.

Enabling shipping exchange

  1. On an AcctVantage Client computer, go to Administration ➤ System Setup.
  2. Select Shipping & XML Import from the drop-down list.
  3. Check the Show Log Window on Server box.
  4. Click the Start button.

Confirming communication from AcctVantage

  1. On the Server computer, open the Shipping folder.
  2. Confirm that the file seen here is named ADEIN. If not look at the Log window in the AcctVantage Server application to get an idea of what may be going wrong. The log found here may indicate that no file was found, or the path was invalid, etc.

Trouble-shooting

  1. Make sure Shipping Exchange is running – see the Shipping & XML Import tab of System Setup. If necessary, click the Start button.
  2. Make sure the path specified is local to the Server computer:
    • On Windows the path would probably look like this: C:\Program Files\AcctVantage ERP Server\Your Company Data\Shipping\
    • On a Mac the path would probably look like this: /Applications/AcctVantage ERP Server/Your Company Data/Shipping/
  3. Make sure that the folder named Shipping has a trailing slash or colon, as appropriate for your operating system.
  4. Make sure that the contents of the files being sent by the shipping software follow the conventions expected by AcctVantage -- see the Files section below for examples.
  5. Make sure that the files being sent to by the shipping software use WINDOWS standard Carriage Return + Line feed within the body of the file. Files created on Mac and Unix systems follow a different standard to denote end of line. If your ADEOUT Request file is picked up by the system without an ADEIN being created, this is the likely cause.

Files

These are the commands/files that get passed back and forth. Each file has on its first line a command in square brackets. That command defines the contents of the file that follow. Based on that command, AV or the shipping software knows what to do next. The standard progression is in the order of the file definitions below. The exception is [CANCEL], which is not part of the normal shipping process. See the Shipping software field map article for definitions of every field.

[REQUEST]

To initiate a shipping transaction, the User enters a [Sales_Document]ID into the shipping software. (This is neither the Order Number nor Invoice Number. It is the record number, which can be determined by clicking on the information icon (the blue "i" in the detailview of the Sales Order screen.) The shipping software then creates a file named ADEOUT.<n> in the shared directory containing the ID of the order to be shipped. (<n> is a number, zero or larger.) A sample [REQUEST] file would look like this:

[REQUEST]
OrdNum=2094

[ORDHD]

In response to this incoming request, AV sends back a file named ADEIN.<n> containing data about the order being shipped. This data is used by the shipping software to calculate shipping charges, generate a tracking number, etc. A sample [ORDHD] file might look like this:

[ORDHD]
OrdNum=0002094
CustNum=4044
Phone=203-854-1234
Company=Marcus Industries
Contact=James Warner
Address=34 Westover Street
DeptFloor=Suite 5
City=Hartford
State=CT
Zip=06716
Weight=23
Terms=C.O.D. Cash
CODAmt=1200.00
PO=125487
ShipVia=UPS 3 Day

[SHIPMENT]

The shipping software responds to the [ORDHD] request by sending a file named ADEOUT.<n> containing info about the shipment. AV uses this info to create a [Shipment] record that’s linked to the [Sales_Document] record. A sample [SHIPMENT] file might look like this:

[SHIPMENT]
OrdNum=0002094
Status=Save
TotFreight=100.15
TotCharges=117.95
TotCODAmt=1317.95
TotHFee=0.0
TotDValue=1000.0
TotWeight=245
TotPkgs=3
Shipped=1
[PKG001]
ShipVia=UPS 3 Day Select HWT
TrackNum=1Z1255450300123995
PkgFreight=74.60
PkgCharges=87.40
BillFreight=Sender
BillAccnt=
COD=COD Cash
CODAmt=887.40
Value=1000.00
Zone=308
Weight=200
[PKG002]
ShipVia=UPS Ground
TrackNum=1Z1255451200124011
PkgFreight=25.55
PkgCharges=30.55
BillFreight=Sender
BillAccnt=
COD=COD Cash
CODAmt=430.55
Value=0.00
Zone=308
Weight=45 

[CANCEL]

If a shipment is canceled in StarShip, StarShip sends a file named ADEOUT.<n> containing this fact. AV picks up this file and deletes the corresponding [Shipment] record. A [CANCEL] file would look like this:

[CANCEL]
OrdNum=2094