StarShip Developer Interface - Shipping Softwaredocs.vtechnologies.com/SS_Dev_Interface.pdf ·...

V-Technologies, LLC

StarShip Developer Interface Using StarShip 10 to provide integrated shipping solutions

www.vtechnologies.com

10 McKee Place

Cheshire, CT 06410

800.462.4016

CONFIDENTIAL – V-Technologies, LLC

Contents

1. Overview ..................................................................................................................................................4

2. Configuration File .....................................................................................................................................4

3. File Formats ..............................................................................................................................................9

3.1. StarShip Request File .................................................................................................................................... 9

3.2. Document File ............................................................................................................................................ 10

3.3. StarShip Shipment File ................................................................................................................................ 18 3.3.1. StarShip Shipment File in XML format........................................................................................... 18 3.3.2. StarShip Shipment File in INI format: ............................................................................................ 38

3.4. Field List File ............................................................................................................................................... 54

3.5. Default Map File ......................................................................................................................................... 57

3.6. Error Message File ...................................................................................................................................... 57

4. Monitoring for StarShip Request and Shipment Files ............................................................................58

4.1. Polling ......................................................................................................................................................... 58

4.2. Windows Change Notification .................................................................................................................... 58

4.3. Windows Messages .................................................................................................................................... 59

5. User Setup and Customization ...............................................................................................................59

5.1. Setup ........................................................................................................................................................... 59

5.2. Customize Interface .................................................................................................................................... 60

5.3. Custom Write Back ..................................................................................................................................... 61

6. The Shipping Process..............................................................................................................................61

6.1. StarShip as Responder ................................................................................................................................ 62

6.2. StarShip as Requestor ................................................................................................................................. 63

7. StarShip 9.x Backwards Compatibility ....................................................................................................64

7.1. Configuration File ....................................................................................................................................... 65

7.2. StarShip 9.x ADE special cases: ................................................................................................................... 66

7.3. Integrate StarShip 10 with a StarShip 9.x compatible Application ............................................................. 66

8. Appendix A – Sample Transactions ........................................................................................................67

8.1 Sample Single Order - XML .....................................................................................................................67

8.2 Sample Multiple-Order - XML ................................................................................................................73

8.3 Sample Customer Document - XML .......................................................................................................82

8.4 Sample Document with Packaging - XML ..............................................................................................85

8.5 Sample Single Order – INI ......................................................................................................................93

8.6 Sample Multiple Order – INI ..................................................................................................................98

8.7 Sample Customer – INI ........................................................................................................................ 106


8.8 Sample Document with Packaging – INI ............................................................................................. 109

8.9 Sample Error message Input ............................................................................................................... 115

8.10 Sample Quote Response – XML ........................................................................................................ 116

8.11 Sample Quote Response – INI ........................................................................................................... 122


1. Overview

The StarShip developer interface allows applications to process shipments using the StarShip user interface.

The two applications communicate by accessing files in a shared folder. The files contain sets of field/value pairs

in a pre-defined structure. The integrated application sends “documents” that the user would like to ship against

such as orders, invoices, or “shipments” (i.e. packed orders). StarShip applies field mappings and value

translations to populate its shipping screen with the document information. When the user processes the

shipment, StarShip returns a file containing the complete shipment -- including packing, rate, and tracking

information.

StarShip supports field mapping so that the actual field names provided in the input documents can be anything.

Ideally the field names closely match the field names seen by the user within the integrated application. A

configuration file provided by the developer of the interface can include “default” or standard field mappings, but

the user will still be able to modify the mappings to customize the interface.

The interface allows either application to initiate the shipping process. StarShip can act as the responder,

handling requests from the integrated application, or StarShip can act as the requestor, sending requests to the

integrated application.

When StarShip is the responder, both applications are running on the workstation. StarShip may be minimized.

The user has the integrated application up and goes to a screen such as order entry or order packing and brings up

a document. The user clicks on a button to ship it, and the document will be written to a file in the shared folder.

StarShip will read the file, apply mapping and translations to it, and bring it up on the screen.

When StarShip is the requestor, the integrated application does not need to be running on the workstation. It

may be running on a server and processing requests from more than one StarShip client. The user initiates the

shipment from within the StarShip shipping screen by entering a document number. StarShip writes a request for

that document number to a shared folder. The integrated application responds and StarShip reads the file,

applies mapping and translations to it, and brings it up on the screen.

In both modes, when the user saves and processes the shipment, StarShip “books” the shipment, prints

documentation and then writes the complete shipment to the shared folder so that the integrated application can

access freight charges and tracking information. The user also has the option to just send back rating information

(a rate quote) without saving or processing the shipment in StarShip.

2. Configuration File

In order for the two applications to communicate, they must know where to look for requests and where to write

the responses. StarShip uses a configuration file which allows the integrated application to specify the

communication information.

Most financial systems allow the user to manage more than one “Company” and each company has its own set of

customers, orders, etc. The configuration file lists the names of the Companies that will be integrating to


StarShip. The user can easily process shipments from multiple companies. If operating in the mode where

StarShip is the requestor, the user can select a company, and then enter a document number. When the

integrated application is the requestor, it will include the company name in the request which will display on the

screen. In both cases, the user can customize mappings and translations separately for each company.

The configuration file must be created by the developer of the interface. If the integrating application supports

multiple companies, then the developer should include code to automatically update this file with the current list

of companies. In addition the Field List can be updated by the integrated application to include actual field values

for each company (see section 3.4). Dynamically updating the Field List is optional, but enhances the user’s ability

to customize field mappings (see section 5).

In StarShip, the user will set up the interface by simply pointing to an existing configuration file. The default

location of the configuration file is %AllUsersProfile%\Application Data\V-Technologies\StarShip

Interface\Configuration.XML (or Configuration.INI if using INI file format). If this location/name is used, the user

will not need to setup the interface in StarShip.

The configuration file contains the following information:

Header A configuration file must contain one Header section.

StarShip Input Path (Required)

Path to a folder where StarShip will receive Document files (see section 3.2 for Document file specifications). This path may contain windows variables to standard paths such as:

%Temp%

%UserProfile%

StarShip Output Path Path to a folder where StarShip will write requests and response files. This path may contain windows variables to standard paths (see StarShip Input Path above). If not provided, the input path will be used.

Input File Name Mask

(Required)

If more than one workstation will be using the same StarShip Input Path, then specify a file mask that allows each StarShip client to determine if the file should be read or ignored. This mask should not be set so that it would include the Output File Name if the StarShip Input and Output paths are the same.

The file mask can contain wild cards (*) and windows variables such as:

%UserName%

%ComputerName%

%Session ID%

%SessionName%

Special:


%StarShip9Station% - StarShip 9.x compatible station number (stored in StarShip.ini in windows folder. See StarShip 9.x backwards compatibility for more. For example:

*_%ComputerName%.%Session ID%

*.XML

StarShip Request File Name If more than one workstation will be using the same StarShip Output Path, then specify a file name that allows the integrated application to determine if the file should be read or ignored.

The StarShip Request File Name can contain windows variables (see Input File Name Mask, above), but it cannot contain any wild card characters (*).

Special Vairable:

%DateTimeStampe% - Along with windows variables, the Shipment File Name only can use this variable. The DateTimeStamp variable will contain the current date and time in format 'yyyy-mm-dd-hh-nn-ss', being the DateTime the file is created. It can be used in conjuncture with other variables to ensure the Shipment File Name is unique and does not overwrite other Shipment files.

This file is always in text (INI file) format.

If the StarShip Request File Name is not provided, then “Request.INI” will be written.

StarShip Shipment File Name If more than one workstation will be using the same StarShip Output Path, then specify a file name that allows the integrated application to determine if the file should be read or ignored.

The StarShip Shipment File Name can contain windows variables (see Input File Name Mask, above), but it cannot contain any wild card characters (*).

The format of this file (XML or INI) will match the format of the Document file produced by the integrated application (see section 3.2 for Document file specifications

If the StarShip Shipment File Name is not provided, then “ShipResult.XML” or “ShipResult.INI” will be written based on the file format.

Interface Name The name of the integrated application. This will appear in StarShip menus, such as “Setup My Application” and will be pre-pended with document names on the Ship screen i.e. “My Application Orders”

This name can be any length, but if longer than 14 characters it will be truncated on some screens (first 11 characters followed by


“…”)

StarShip Mode Request/Respond. (Default is Request).

Broadcast Message Y/N, Default is “N”. Provided for backwards compatibility with StarShip 9.x interfaces. StarShip and integrated application will broadcast a windows message when a file is written. See section 4 for details.

Header\Document One section for each document type that will be available in all companies. If not specified will default to one document “Order”.

Name (Required)

Use this to set the document name, for example “Invoice”, “Order”, or “Return”.

Type (Required)

“C” Customer – contains a contact list entry such as the information for one customer or vendor.

“O” Order – Contains one or more sales transactions with ship from, ship to, and line item information. Can be used for orders, invoices, rma’s. Multiple transactions/orders to the same destination can be included in one file.

“S” Shipment – contains one or more transactions (orders to the same destination) with line item information plus packaging information. This is used if the integrated application has the ability to pack orders in preparation for shipping.

Field List (Required)

Path to an .XML file containing a list of all possible fields and their descriptions. For enumerated types, this file can also include a list of possible values. This is useful for the customer when creating or modifying mappings. See section 3.4 for details on the format of this file.

Default Map Path to an XML file containing default mapping from source document to StarShip. See section 3.5 for details on the format of this file.

Company A configuration file must contain at least one Company section.

Name (Required)

The name of the company. Must be unique among company entries.

The configuration file can be formatted as XML or as an INI file.

XML File example:

<Configuration>

<Header>

<NameValue Name="StarShip Input Path" Value="%AllUsersProfile%\Application Data\V-

Technologies\StarShip Interface\"/>

<NameValue Name="Input File Name Mask" Value="Input.XML"/>

<NameValue Name="StarShip Request File Name" Value="Request.INI"/> 

<NameValue Name="StarShip Shipment File Name" Value="ShipResult.XML"/>

<NameValue Name="StarShip Mode" Value="Respond"/>

<NameValue Name="Interface Name" Value="Custom Warehouse"/>

<Document>

<NameValue Name="Name" Value="Sales Orders"/>

<NameValue Name="Type" Value="O"/>

<NameValue Name="Field List" Value="%AllUsersProfile%\Application Data\V-Technologies\StarShip

Interface\SalesOrderFields.XML"/>

<NameValue Name="Default Map" Value="%AllUsersProfile%\Application Data\V-Technologies\StarShip

Interface\SalesOrderMap.XML"/>

</Document>

<Document>

<NameValue Name="Name" Value="Customers"/>

<NameValue Name="Type" Value="C"/>


Interface\CustFields.XML"/>


Interface\CustMap.XML"/>

</Document>

<Document>

<NameValue Name="Name" Value="Vendors"/>

<NameValue Name="Type" Value="C"/>


Interface\VendFields.XML"/>


Interface\VendMap.XML"/>

</Document>

</Header>

<Company>

<NameValue Name="Name" Value="ABC Company"/>

</Company>

<Company>

<NameValue Name="Name" Value="XYZ Company"/>

</Company>

</Configuration>

INI File example:

[Header]

StarShip Input Path=AllUsersProfile%\Application Data\V-Technologies\StarShip Interface\

Input File Name Mask=Input.XML

StarShip Request File Name=Request.INI (Requestor mode only)

StarShip Shipment File Name=ShipResult.XML

StarShip Mode=Respond

Interface Name=Custom Warehouse

[Document1]

Name=Sales Orders

Type=O

Field List=%AllUsersProfile%\Application Data\V-Technologies\StarShip Interface\SalesOrderFields.XML

Default Map=%AllUsersProfile%\Application Data\V-Technologies\StarShip Interface\SalesOrderMap.XML

[Document2]

Name=Customers

Type=C

Field List=%AllUsersProfile%\Application Data\V-Technologies\StarShip Interface\CustFields.XML


Default Map=%AllUsersProfile%\Application Data\V-Technologies\StarShip Interface\CustMap.XML

[Document3]

Name=Vendors

Type=C

Field List=%AllUsersProfile%\Application Data\V-Technologies\StarShip Interface\VendFields.XML

Default Map=%AllUsersProfile%\Application Data\V-Technologies\StarShip Interface\VendMap.XML

[Company1]

Name=ABC Company

[Company2]

Name=XYZ Company

3. File Formats

The StarShip Developer Interface supports two text formats: XML and INI file.

3.1. StarShip Request File

When StarShip is set up as the Requestor, it writes the StarShip Request File to the StarShip Output Path (StarShip

Input Path if Output Path is not specified). This file is always in text (INI file) format and contains the following

fields:

Request A configuration file must contain one Request section.

Company The currently selected Company on the StarShip ship screen in the Source panel. The Company drop-down list will be populated with the Company Name defined in the configuration file in the Company section.

Document Type The currently selected Document on the StarShip ship screen in the Source panel. The Document drop-down list will be populated with the Interface Name + Document Name (where Interface Name is in the Header section of the configuration file and Document Name values are in the Company\Documents section). Only the Document Name portion will be sent in Document Type.

Document Key This is the number entered by the shipper in the first entry box in the Source panel (will have caption “Interface Name + Document Name”).

OrdNum For backwards compatibility with StarShip 9.x, the request field OrdNum will also contain the Document Key.

The StarShip user enters a document number/name in the Source section of the StarShip Ship window and

presses <Enter> to generate the StarShip Request File.


Sample StarShip Request File:

[REQUEST]

Company=ABC Company

DocumentKey=543

DocumentType=Sales Orders

OrdNum=543

3.2. Document File

A Document file contains a representation of a document sent from the integrated application to StarShip. The

integrated application will write the document file to the StarShip Input Path in these two cases based on the

StarShip Mode (StarShip Input Path and StarShip Mode are defined in the configuration file):

1. When the StarShip Mode is Requestor, the Document file will be written by the integrated application

with the document specified in the StarShip Request file.

2. When the StarShip Mode is Responder, the Document File will be written by the integrated application

based on some event within that application. For example, the user may have a “StarShip” button or a

special control key available on the order entry screen.

Creating the Document file is the most important part of implementing a StarShip integration. How this file is

created and the data that it contains will determine how well the integration serves users now and in the future.

The goals when creating this document are:

Insulate the integration from changes in StarShip: Ideally, the integration should not need to be updated

when StarShip functionality expands. Only if new shipping-related data is added to the integrated

application should the integrator need to modify the code that generates the document file contents.

Provide transparency for individual users into how the integration works – i.e. how data from the

integrated application populates the shipment.

Allow individual users of the integration to easily customize the interface without the developer’s

intervention. For example, applications often have user-definable fields that users may populate with

shipping information. The developer of the interface can’t know how each user will make use of these

fields so the user needs to be able to map them to the shipment.

These goals can be accomplished by ensuring that the Document file represents the relevant data that is available

in the integrated application and does not attempt to provide the specific fields which make up a StarShip


shipment. StarShip will convert the document to a shipment by mapping and translating the field values before

populating the shipping screen. The developer may spend more time up front adding all fields in the source

document that might be used by the shipper, and providing a field list and default mapping file. However, in the

long run the integration will require less maintenance by the developer.

File Formats

The Document file can be in XML or INI file format and contains name/value pairs which represent fields

organized into sections. The sections have pre-defined relations to each other and some sections can repeat, such

as line items per order. StarShip reads or ignores different sections based on the document type (as defined in

the Document section of the configuration file).

The name/value pairs are meant to represent data fields in the source document. They should contain the name

of a field as it appears to the user within the integrated applications. This allows the interface to be self-

documenting: the user can view and modify the mappings in StarShip’s Customizer screen and easily understand

what values are being used as input to the StarShip shipment.

XML Format:

In XML format, the sections are XML elements. The name/value pairs are contained in a Row element with

attributes “FieldName” and “Value”:

<Row FieldName="Unit Of Measure" Value="EACH" />

Section For Document Type

Description

SelectResult All Root node. Contains one Document section for document type “C”. Contains one or more Document section for document types “O” and “S”. May also contain a Packaging section and a HandlingUnits section for document type “S”.

Document All Contains the Header and LineItems sections. This element also contains the following attributes:

DocumentType – must match a document name in the configuration file

DocumentKey – the document number or id

CompanyName – must match a company in the configuration file

Header All Contains field/value pairs which occur once per document.

LineItems O, S Contains one or more LineItem entries.

LineItem O, S Contains field values which are at the line item level. This element also contains the following attribute:

LineNumber = sequential number for line.


Packaging S Contains one or more Package sections. Ignored for document types other than “S”. Note this section is not within a Document section because Packages may contain items from more than one document.

Package S Contains field values which are at the package level. Contains one PackageContents element.

Package ID – If specified will be used as unique identifier for the package. This field will also be present in the Shipment File with the same value for the package (See Shipment File section for more details). This field does NOT have to be listed in the Field List xml to be recognized. The field name is case sensitive and must be exactly ‘Package ID’.

PackageContents S Contains one or more Contents elements.

Contents S Contains field value pairs at the package contents level. Contains the following attributes:

DocumentKey – must match the DocumentKey attribute in a Document section above.

LineNumber– must match a line number in the LineItem section for the Document with DocumentKey

HandlingUnits S Contains one or more HandlingUnit sections. Ignored for document types other than “S”. Note this section is not within a Document section because Handling Units (i.e. pallets) may contain items packed from more than one document.

HandlingUnit S Contains field values which are at the HandlingUnit level.

Handling Unit ID – If specified will be used as unique identifier for the Handling Unit. The value passed in this field will be returned in the Internal Handling ID field in the Shipment File (See Shipment File section for more details). This field does NOT have to be listed in the Field List xml to be recognized. The field name is case sensitive and must be exactly ‘Handling Unit ID’.

XML Example:

Additional Sales Orders could be included in this document file (to be merged into one shipment) by adding

Document elements. Note that this example includes FSI fields “User Field 1” and “Item User Field 1” to

demonstrate that any field from the financial system (including user defined/custom fields) can be sent to

StarShip, providing they are listed in the Field List and Map files identified in the Configuration file. Any field

included in the document file that is not included in the Field List and Map files will be ignored by StarShip. This

example also includes Packaging elements for demonstration purposes. As indicated by the previous chart,

Packaging is only valid for Shipment documents.

<SelectResult>
















</Header>

<LineItems>









</LineItem>









</LineItem>









</LineItem>

</LineItems>

</Document>

</SelectResult>

Note:

In the XML example above the following line contains an entity reference:

<Row FieldName=" Item Code Description" Value="DESK 72" X 30"" />

When viewed as text we see that the double quotes within the “Value” attribute have been replaced by entity

references ("). The actual value is DESK 72” X 30”. This substitution will be automatic if you use an XML

parser or XML tool to create your XML document. If writing the document as an ordinary text file, you must be

aware that entity references must replace characters not allowed in XML, as shown in the table below:


Entity Reference Meaning < < (less than) > > (greater than) & & (ampersand)

' ' (apostrophe or single quote) " " (double quote)

If using non-ASCII characters, it is recommended that you provide the appropriate code page to the XML. The

encoding used should match the code page. If no code page provided, StarShip defaults to using “ISO-8859-1”.

INI File Format

In the INI file format, the sections are ini file sections (in brackets) and name/value pairs are keys:

Unit of Measure=Each

The # after the section name is an incrementing number which uniquely identifies a section when multiple

instances of a section are allowed.

Section For Document Type

Description

Document#

( ORDHD# for backwards compatibility)

All Contains the Header and LineItems sections. If only one instance of this section, the # can be omitted.

This section contains the following name/value pairs:

DocumentType – must match a document name in the configuration file. For backwards compatibility, if not provided will use 1st document type.

DocumentKey – required - the document number or id (OrdNum for backwards compatibility)

CompanyName – must match a company in the configuration file. For backwards compatibility, if not provided will use first company name.

Item#

(ITM# for backwards compatibility)

O, S Contains field values which are at the line item level. # is the Line Number.

Package_#

(PKG# for backwards compatibility)

S Package entries should be included after all Document# and Item# entries and are allowed for “S” type documents only. Contains field values which are at the package level. # is the Package Number.


Contents_#_9 S One or more contents entries are used to describe the contents of a package. # is the Package sequence number this contents section belongs to. 9 is the contents sequence. Each Contents# entry should contain the following field/value pairs:

PackageNumber - must match a Package number above.

LineNumber- must match an Item Index for the DocumentKey above.

DocumentKey – must match a DocumentKey or OrdNum key above (optional if only one document is included in the file)

Quantity – number of ItemNumber contained in PackageNumber

Unit_# S Unit entries should be included after all Document# and Item# entries and are allowed for “S” type documents only. Contains field values which are at the handling unit level. # is the handling unit Number.

INI Example

Note that additional Sales Orders could be included in this document file (to be merged into one shipment) by

adding [Document#] elements with their associated [Item#] sections prior to any Package# or Contents# sections.

[Document1] ; Note: [ORDHD], [Document1], [ORDHD1] are all correct for this section name

DocumentKey=2066

CompanyName=Sample Retail Company

DocumentType=Orders

Cust No.=XTOINC-01

Order No.=2066

PO Number=09-31

Ship To Address Line 1=EMERALD POINTE GOLF CLUB

Ship To Address Line 2=7000 HOLIDAY ROAD

Ship To Name=LAKE LANIER ISLAND RESORT

Ship To Country=United States of America

Ship To City=BUFORD - LAKE LANIER ISLAND

Ship To Zip=30518

Ship To State=GA

Order Total=1723.78

Ship Via=TRUCK

Terms=1.5% -10 - 30

Company Name=Dewitt - Play

Company Address 1=905 South Kingshighway

Company Address 2=

Company City=Sikeston

Company State=MO

Company Zip code=63801

Company Phone=573-472-0048

Company Contact person=

Ship To Contact Name=

Ship To Phone=256-766-2091

Ship Date=11/19/2008

[Item1_1]

Item No.=CUSTOM_SEW1

Item Sequential Number=1


Item Description=SB GRNGARD 62FT X 75FT 1A 1B

Ordered Units=2

Item Unit Price=416.18

Unit Weight=45

Item UOM=EA

[Item1_2]




Ordered Units=2


Unit Weight=32.5

Item UOM=EA

[Document2]

DocumentKey=2067


DocumentType=Orders

Cust No.=XTOINC-01

Order No.=2067

PO Number=09-32






Ship To Zip=30518

Ship To State=GA

Order Total=2832.64

Ship Via=TRUCK

Terms=1.5% -10 - 30



Company Address 2=


Company State=MO







[Item2_1]




Ordered Units=3


Unit Weight=45

Item UOM=EA

[Item2_2]




Ordered Units=2


Unit Weight=32.5

Item UOM=EA

[Item2_3]





Ordered Units=2


Unit Weight=25

Item UOM=EA

3.3. StarShip Shipment File

The StarShip Shipment file contains information about the shipment to be sent back to the integrated application.

The StarShip Shipment file is written to the StarShip Output Path defined in the configuration file (the StarShip

Input Path is used if the output path is not defined). The name of the file is determined by the StarShip Output

File Name, also defined in the configuration file.

When the user is ready to confirm the shipment, they will click the Save and Process button and the

shipment will be confirmed to the carrier, saved to StarShip’s database and the complete shipment

information will be written to the StarShip Shipment File.

If the user clicks the Return Quote button, the current shipment will be written to the StarShip Shipment

File. The shipment will not be confirmed to the carrier. If the user had not clicked the “Save” button, the

shipment would not be saved to StarShip’s database.

If the user clicks “New” or exits StarShip, a Shipment File containing a “cancel” status will be written.

If the user voids a previously booked shipment in StarShip, a Shipment File containing a “delete” status

will be written.

The format of the Shipment file (XML or INI) will be the same as the Document File sent by the integrated

application.

3.3.1. StarShip Shipment File in XML format

Section Description

WriteBack Root node of StarShip Shipment XML file. Contains one or more SourceDocument elements, one Packaging element, and one Settings element.

SourceDocument Contains one TrackInfo element, one FreightInfo element, and may contain one OrderItems element. The SourceDocument element also contains the following attributes:

DocType – Document Type

DocKey1 – Document Key (ID of document being processed – Order#, Customer ID, etc.)

CompanyName – Company Name

TrackInfo Contains the following attributes which allow the developer to add/update a notes or comments type text field in the source document with shipping information. The user can set up which shipping data elements and “tags” will be included in the text:


TrackingInfo – a string containing shipping information which starts with the StartDelimiter text and ends with EndDelimiter text.

StartDelimiter – value used to find the start of any existing notes in the source document text field.

EndDelimiter – value used to find the end of any existing notes in the source document text field.

FreightInfo Contains one Shipment element.

Shipment Contains NameValue elements with freight information.

Shipment\NameValue Each NameValue element under Shipment contains Name, Value and ValueType attributes, with the following names/meaning:

ValueType: Will be ‘Source’ for Custom Write-Back fields, ‘Shipment’ for the standard StarShip Write-Back Fields documented below.

Note: There can be unlimited UDEF fields. New standard fields may be added in later versions.

Name Value

Shipment Number Input document Key

Order Number Order Number

PO Number PO Number

Department Department specified on the Shipment Tab

DocumentType Input document type

DocumentKey Input document Key

OrdNum Order Number: For backwards compatibility

ID Freight Shipments: Will contain PRO number

if available, otherwise BOL number

Parcel Shipments: Comma delineated list of

Tracking numbers.

Tracking Number Comma delineated list of Tracking numbers

for Parcel Shipments

MasterTrackingID Master Tracking Number

InternalID StarShip Internal Shipment Record Unique identifier

BOLNumber BOL Number


PRONumber PRO Number

Status Add – means user clicked “Ship / Process”

Button

Cancel – means user clicked “New” or exited

StarShip

Quote – means user clicked “Return Quote”

button

Delete – means user clicked “Void Shipment”

Button

DeltaFreight Change in Freight (When shipping against

Same order multiple times or voiding it)

CODAmount Total shipment COD Amount

COD Freight Tax Amount Freight Tax amount

COD Base Amount COD amount before Tax/Freight is added

Order Number Order Number from the Order Number Tab

Freight Billing Billing Type

Freight Account Billed account number

Department Department Number from the Shipment Tab

Customer Number Customer Number from the Recipient Tab

CarrierType Integer value representing whether it is a Parcel or

Freight Shipment.

0 = Freight

1 = Parcel

Service Code

ReturnShipment Y or N value indicating if shipment was a

return shipment.

User ID StarShip User that Processed the Shipment

Declared Value Total Declared Value option amount

Freight

Total freight charges

Total shipment weight


Weight

Carrier

Carrier Name

Service

Service selected for shipment

SCAC

SCAC code for carrier

ReadyDate

Date shipment will be ready for pickup.

DeliveryDate

Estimated Delivery Date.

Freight cost

Delivery and Options charges

Fuel surcharge

Fuel Surcharge

Handling Fee

User-defined handling fee

Notes Contains a string of shipping information

which developer can use to update notes or

comments in the source document. user

can set up which shipping data elements and

“tags” will be included in the text. The tags

<CR> should be replaced with returns

before writing text.

Shipment User Defined 1 - 5

Shipment tab User Field 1 - 5

(Original Format – for backwards compatibility)

Shipment Field 1 – 5 Shipment tab Shipment Field 1

(Default 5 UDEFS – can be customized)

User Defined 1 - 5 Order Tab Order Field 1 - 5


Order Field 1 – 5 Order Tab Order Field 1 - 5



Applied Charges Freight

Charges

Freight charge after Freight Rules and User-defined

handling fee applied

Applied Charges

Accessorial Charges

Accessorial charges after Freight Rules and User-

defined handling fee applied

Applied Charges Handling

Fee

User-defined handling fee after Freight Rules applied


Cost

Freight charge after Freight Rules and User-defined


Applied Charges Fuel

Surcharge

Fuel Surcharge after Freight Rules and User-defined


Applied Charges Total Total Freight charges after Freight Rules applied

List Charges Freight

Charges

Published rate Freight Charge

List Charges Surcharges Published rate surcharges

List Charges Discounts Published rate discounts

List Charges Accessorial

Charges

Published rate accessorial charges

List Charges Misc Charges Published miscellaneous Charges

List Charges Total Total of Published rated charges

Contract Charges Freight

Charges

Custom rate Freight Charges

Contract Charges

Surcharges

Custom rate surcharge

Contract Charges

Discounts

Custom rate discounts

Contract Charges

Accessorial Charges

Custom rate accessorial charges

Contract Charges Misc

Charges

Custom rate miscellaneous charges


Contract Charges Total Total of custom rated charges

eCommerceOrderNumber eCommerce Order Number

OrderItems SourceDocument element will contain one OrderItems element if line item information was provided for the document. The OrderItems element contains one or more OrderItem elements.

OrderItem Each OrderItem element contains NameValue elements with the following names, meanings:

OrderItem\NameValue Each NameValue element under OrderItem contains a Name, Value and ValueType attribute, with the following names/meaning:



Name Value

ItemNumber Item Number

ShipQty Ship Quantity

UOM Unit of Measure

Extra Key1 – 3 If Extra Key was mapped on import, will be written back. Extra Keys allows for multiple line Items of the same Item Code to be imported separately.

User Defined 1 – 5 Line Item User Defined Fields 1 - 5


Item Field 1 - 5 Item Field 1 – 5


DeltaShipQty Change in ShipQty (When shipping against Same order multiple times or voiding it)

eCommerceItemNumber The key that identifies the line item in the eCommerce order, such as the ASIN, SKU, etc.

Packaging The Packaging element contains one or more Package elements.

Package One package element is included for each 1st level package in the shipment. Each


Package entry contains several NameValue elements and a PackageContents element.

Package\NameValue Each NameValue element under Package contains a Name, Value and ValueType attribute, with the following names/meaning



Name Value

Package Number Sequential Package Number (1…n)

Package ID Index number for imported packages:

If Document file imported contains Package

ID field with a valid value, the same value is

returned in the Shipment file. Value has to

be a positive integer.

For packages added manually by user will

always be -1.

Package Quantity One package entry can represent multiple physical

packages. For example, the user can pack 25

widgets into two medium boxes without specifying

exactly how they are distributed.

Packaging Packaging name which displays on the Packaging tab

in the Package Info group.

Package Type Base type of package on the Packaging tab in the

Package Info group

Freight Class Freight class for this package (highest class of items

contained within)

Length Length of the package in inches

Height Height of the package in inches

Width Width of the package in inches

Calculated Weight Weight (in pounds) of the package calculated by

adding contents weight and the weight of the


packaging itself. Automatically converted from

specified UOM to pounds.

Actual Weight Same as Calculated Weight unless user enters an

overriding value.

Packaging Weight Weight (in pounds) of the package itself (Tare

weight)

Actual Weight in UOM Weight in the UOM specified for the Package.

Weight UOM The Weight Unit Of Measure

License Plate License Plate Field from the Shipment for that

package

Package Content Package Contents Field from the Shipment for that package

Tracking Number Package Tracking Number

SSCC Container ID (SSCC) field in the Package group on the 'Packaging' tab.

Billed Weight Package Billed Weight (in pounds, greatest of Dimensional Weight vs. Actual Weight)

Charges Total Applied Charges for backwards compatibility

User Defined 1 - 5 Package User Defined Fields 1 – 5


Pack Field 1 - 5 Pack Field 1 - 5


Reference 1 - 5 Carrier Reference Fields mapped to package user defined fields for this shipment. Will only be present if setup in Carrier settings.



Declared Value Declared Value option amount per package

COD Type COD Type


COD Amount COD Amount per package

Hazardous Y or N value indicating if package contained Hazardous Items

Handling Fee User-defined handling fee per package

Zone Delivery Zone


Charges Freight charge after Freight Rules and User-defined handling fee applied

Applied Charges

Accessorial Charges Accessorial charges after Freight Rules and User-defined handling fee applied


Fee User-defined handling fee after Freight Rules applied



Cost Freight charge after Freight Rules and User-defined handling fee applied


Surcharge Fuel Surcharge after Freight Rules and User-defined handling fee applied

List Charges Freight

Charges Published rate Freight Charge




Charges Published rate accessorial charges




Charges Custom rate Freight Charges

Contract Charges

Surcharges Custom rate surcharge

Contract Charges Custom rate discounts


Discounts

Contract Charges

Accessorial Charges Custom rate accessorial charges


Charges Custom rate miscellaneous charges

Contract Charges Total Total of custom rated charges

PackageContents Contains one or more Contents elements

Contents Contents contains several NameValue elements.

Contents\NameValue Each NameValue element under Contents contains a Name and Value attribute, with the following names/meaning:

Note that new fields may be added in later versions.

Name Value

Package Content Quantity Quantity of an item specified by this Contents entry

Package Content UOM Unit of Measure of the item specified by this Contents entry this package

Package Content Item Number

Item number of the item specified by

this Contents entry

Package Content Sales Order

Order number (as mapped from SourceDocument) specified by this Contents entry.

Package Content Extra Key1 - 3

Extra Key of the item specified by this Contents entry.

Settings User settings regarding how Shipment file should be handled by integrated application. Contains several NameValue elements.

Settings\NameValue Each NameValue element under the Settings contains a Name and Value attribute, with the following names/meaning:

Name Value

UpdateFreightFlag Y if User wants freight applied to source document(s).

UpdateTrackingFlag Y if User wants tracking information updated in source document(s).


HandlingUnits The HandlingUnits element contains one or more HandlingUnit elements.

HandlingUnit One HandlingUnit element is included for each 1st level Handling Unit (pallet) in the shipment. Each HandlingUnit entry contains several NameValue elements.

HandlingUnit\NameValue Each NameValue element under HandlingUnit contains a Name and Value attribute, with the following names/meaning:


Name Value

Handling Unit Number Sequential Handling Unit Number (1…n)

Handling Unit ID StarShip Handling Unit ID (Same as Handling Unit

Number)

Handling Unit Internal ID Index number for Handling Units:

For Handling Units imported with valid value

in the “Handling Unit ID” field of the

Document file, the value will be the same as

what was imported. Value has to be an

positive integer.

For Handling Units imported without a

“Handling Unit ID”, the value will be the

same as “Handling Unit Number”

For Handling Units added manually in

StarShip, the value will always be -1

Handling Unit Quantity One Handling Unit entry can represent multiple

physical pallets. For example, the user can pack 10

boxes into two pallets without specifying exactly

how they are distributed.

Handling Unit Packaging Packaging which displays on the Packaging tab in the

Package Info group.

Handling Unit Package

Type

Base type of Handling Unit on the Packaging tab in

the Package Info group

Handling Unit Freight Class Freight class for this Handling Unit (highest class of


Packages contained within)

Handling Unit Length Length of the Handling Unit in inches

Handling Unit Height Height of the Handling Unit in inches

Handling Unit Width Width of the Handling Unit in inches

Handling Unit Calculated

Weight

Weight of the Handling Unit calculated by adding

weight of contents and weight of the Handling Unit

itself.

Handling Unit Actual

Weight

Same as Calculated Weight unless user enters an

overriding value

Handling Unit Packaging

Weight

Weight of the Handling Unit itself

Zone Delivery Zone

SSCC Container ID (SSCC) field in the Handling Unit group

on the 'Packaging' tab.

License Plate License Plate

Handling Unit User Defined

1 - 5

Handling Unit User Defined Fields 1 – 5


Pallet Field 1 - 5 Pallet Field 1 - 5


Sample StarShip Shipment File in XML format (note that the TrackingInfo section is a string value, and the
is

an XML entity reference for carriage return within that string):

<?xml version="1.0" encoding="ISO-8859-1" ?>

<WriteShipment>

<SourceDocument DocKey1="2066" DocumentKey1="2066" DocKey2="2066" DocumentKey2="2066"

DocType="Order" DocumentType="Order" SourceCompanyName="Sample Retail Company" SourceID="94"

eCommerceName="" eCommerceCompanyName="">

<FreightInfo>

<Shipment>

<Sender ID="" NAME="Dewitt - Play" CONTACT="" ADDRESS1="905 South

Kingshighway" ADDRESS2="" ADDRESS3="" CITY="Sikeston" STATE="MO" ZIP="63801" COUNTRY="US"

PHONE="5734720048" EMAIL="" RESIDENTIAL="False"/>

<Recipient ID="XTOINC-01" NAME="LAKE LANIER ISLAND RESORT"

CONTACT="" ADDRESS1="EMERALD POINTE GOLF CLUB" ADDRESS2="7000 HOLIDAY ROAD" ADDRESS3=""


CITY="BUFORD - LAKE LANIER ISLAND" STATE="GA" ZIP="30518" COUNTRY="US" PHONE="2567662091" EMAIL=""

RESIDENTIAL="False"/>

<BillTo ID="FQ" NAME="Freightquote.com" CONTACT="" ADDRESS1="16025 W

113th St" ADDRESS2="" ADDRESS3="" CITY="Lenexa" STATE="KS" ZIP="66219" COUNTRY="US"


<NameValue Name="CarrierType" Value="0" ValueType="Shipment"/>

<NameValue Name="ID" Value="BOL:70873044" ValueType="Shipment"/>

<NameValue Name="BOLNumber" Value="70873044" ValueType="Shipment"/>

<NameValue Name="PRONumber" Value="" ValueType="Shipment"/>

<NameValue Name="MasterTrackingID" Value="70873044"

ValueType="Shipment"/>

<NameValue Name="Status" Value="Add" ValueType="Shipment"/>

<NameValue Name="DeltaFreight" Value="109.39" ValueType="Shipment"/>

<NameValue Name="Freight" Value="109.39" ValueType="Shipment"/>

<NameValue Name="CODAmount" Value="0.00" ValueType="Shipment"/>

<NameValue Name="COD Freight Tax Amount" Value="0.00"


<NameValue Name="COD Base Amount" Value="0.00"


<NameValue Name="Declared Value" Value="0.00" ValueType="Shipment"/>

<NameValue Name="Weight" Value="155.00" ValueType="Shipment"/>

<NameValue Name="Service" Value="LTL" ValueType="Shipment"/>

<NameValue Name="Service Code" Value="LTL" ValueType="Shipment"/>

<NameValue Name="SCAC" Value="DAFG" ValueType="Shipment"/>

<NameValue Name="Carrier" Value="Dayton Freight Lines"


<NameValue Name="ReadyDate" Value="12/07/2015"


<NameValue Name="Delivery Date" Value="12/10/2015"


<NameValue Name="Order Number" Value="2066" ValueType="Shipment"/>

<NameValue Name="eCommerceOrderNumber" Value=""


<NameValue Name="Customer Number" Value="XTOINC-01"


<NameValue Name="PO Number" Value="09-31" ValueType="Shipment"/>

<NameValue Name="Department" Value="" ValueType="Shipment"/>

<NameValue Name="Shipment ID" Value="7" ValueType="Shipment"/>

<NameValue Name="ReturnShipment" Value="N" ValueType="Shipment"/>

<NameValue Name="Freight Billing" Value="S" ValueType="Shipment"/>

<NameValue Name="Freight Account" Value="[email protected]"


<NameValue Name="User ID" Value="admin" ValueType="Shipment"/>

<NameValue Name="Shipment User Defined 1" Value=""










<NameValue Name="User Defined 1" Value="" ValueType="Shipment"/>





<NameValue Name="Shipment Field 1" Value="" ValueType="Shipment"/>









<NameValue Name="Item Field 1" Value="" ValueType="Shipment"/>





</OrderItem>

<OrderItem>




















</OrderItem>

</OrderItems>

</SourceDocument>




<FreightInfo>

<Shipment>

<Sender ID="" NAME="Dewitt - Play" CONTACT="" ADDRESS1="905 South

Kingshighway" ADDRESS2="" ADDRESS3="" CITY="Sikeston" STATE="MO" ZIP="63801" COUNTRY="US"


<Recipient ID="XTOINC-01" NAME="LAKE LANIER ISLAND RESORT"

CONTACT="" ADDRESS1="EMERALD POINTE GOLF CLUB" ADDRESS2="7000 HOLIDAY ROAD" ADDRESS3=""

CITY="BUFORD - LAKE LANIER ISLAND" STATE="GA" ZIP="30518" COUNTRY="US" PHONE="2567662091" EMAIL=""


<BillTo ID="FQ" NAME="Freightquote.com" CONTACT="" ADDRESS1="16025 W

113th St" ADDRESS2="" ADDRESS3="" CITY="Lenexa" STATE="KS" ZIP="66219" COUNTRY="US"






<NameValue Name="MasterTrackingID" Value="70873044"






<NameValue Name="COD Freight Tax Amount" Value="0.00"


<NameValue Name="COD Base Amount" Value="0.00"








<NameValue Name="Carrier" Value="Dayton Freight Lines"


<NameValue Name="ReadyDate" Value="12/07/2015"


<NameValue Name="Delivery Date" Value="12/10/2015"



<NameValue Name="eCommerceOrderNumber" Value=""


<NameValue Name="Customer Number" Value="XTOINC-01"







<NameValue Name="Freight Account" Value="[email protected]"






























<NameValue Name="CUSTOMWB1" Value="Leave at back door"

ValueType="Source"/>

</Shipment>

</FreightInfo>

End Shipment(s)"


<OrderItems>

<OrderItem>





















</OrderItem>

<OrderItem>




















</OrderItem>

<OrderItem>




















</OrderItem>

</OrderItems>

</SourceDocument>

<BatchName/>


<Row Name="Contract Charges Freight Charges" Value="0.00"


<Row Name="Contract Charges Surcharges" Value="0.00" ValueType="Shipment"/>

<Row Name="Contract Charges Discounts" Value="0.00" ValueType="Shipment"/>

<Row Name="Contract Charges Accessorial Charges" Value="0.00"


<Row Name="Contract Charges Misc Charges" Value="0.00"


<Row Name="Contract Charges Total" Value="0.00" ValueType="Shipment"/>

<PackageContents>

<Contents>

<Row Name="Package Content Quantity" Value="2" ValueType="Shipment"/>

<Row Name="Package Content UOM" Value="EA" ValueType="Shipment"/>

<Row Name="Package Content Item Number" Value="CUSTOM_SEW1"


<Row Name="Package Content Sales Order" Value="2066" ValueType="Shipment"/>

<Row Name="Package Content Extra Key1" Value="" ValueType="Shipment"/>



</Contents>

<Contents>









</Contents>

</PackageContents>

</Package>

<Package>















<Row Name="Package Content" Value="SB GRNGARD 25FT X 83FT 2A 2B"



















</Contents>

</PackageContents>

</Package>

</Packaging>

<HandlingUnits>

<HandlingUnit>


<Row Name="Handling Unit Internal ID" Value="-1" ValueType="Shipment"/>

<Row Name="Handling Unit Number" Value="1" ValueType="Shipment"/>

<Row Name="Handling Unit Quantity" Value="1" ValueType="Shipment"/>

<Row Name="Handling Unit Packaging" Value="Custom Pallet"


<Row Name="Handling Unit Freight Class" Value="65" ValueType="Shipment"/>

<Row Name="Handling Unit Length" Value="0" ValueType="Shipment"/>

<Row Name="Handling Unit Height" Value="0" ValueType="Shipment"/>

<Row Name="Handling Unit Width" Value="0" ValueType="Shipment"/>

<Row Name="Handling Unit Calculated Weight" Value="405.00"


<Row Name="Handling Unit Actual Weight" Value="405.00"


<Row Name="Handling Unit Packaging Weight" Value="0.00"


<Row Name="Handling Unit Actual Weight in UOM" Value="405.00"


<Row Name="Handling Unit Weight UOM" Value="lbs" ValueType="Shipment"/>




<Row Name="Handling Unit Package Type" Value="Pallet" ValueType="Shipment"/>

<Row Name="Handling Unit User Defined 1" Value="" ValueType="Shipment"/>





<Row Name="Pallet Field 1" Value="" ValueType="Shipment"/>





</HandlingUnit>

</HandlingUnits>

</WriteShipment>

3.3.2. StarShip Shipment File in INI format:

Section Description

Shipment_### Shipment File will contain one Shipment section for each source Document section included in the Document input file.

If only one instance of this section, the ### will be omitted.

This section contains the following name/value pairs. Additional Name/value pairs may be present if Custom Write-Back fields are mapped. Custom Fields are defined in the Field List File.



Name Value


OrdNum Order Number

DocumentType Input document type

DocumentKey Input document Key

OrdNum Order Number: For backwards compatibility

ID Freight Shipments: Will contain PRO

number if available, otherwise BOL

number.

Parcel Shipments: Comma delineated list

Of Tracking numbers.

Tracking Number Comma delineated list of Tracking

numbers for Parcel Shipments

MasterTrackingID Master Tracking Number

InternalID StarShip Internal Shipment Record Unique identifier

BOLNumber BOL Number

PRONumber PRO Number

Status Add – means user clicked “Ship /

Process” Button

Cancel – means user clicked “New” or

Exited StarShip

Quote – means user clicked “Return

Quote” button

Delete – means user clicked “Void

Shipment” Button

DeltaFreight Change in Freight (When shipping against

Same order multiple times or voiding it)

CODAmount Total shipment COD Amount

COD Freight Tax Amount Freight Tax amount


Order Number Order Number from the Order Number

Tab



Department Department Number from the Shipment

Tab

Customer Number Customer Number from the Recipient Tab

CarrierType Integer value representing whether it is a

Parcel or Freight Shipment.

0 = Freight

1 = Parcel

Service Code

ReturnShipment Y or N value indicating if shipment was a

return shipment.

User ID StarShip User that Processed the Shipment

Declared Value Total Declared Value option amount

Freight

Total freight charges

Weight

Total shipment weight

Carrier

Carrier Name

Service

Service selected for shipment

SCAC

SCAC code for carrier

ReadyDate

Date shipment will be ready for pickup.

Freight cost

Delivery and Options charges


Fuel surcharge Fuel Surcharge

Handling Fee

User-defined handling fee

Notes Contains a string of shipping information

which developers can use to update notes

or comments in the source document.

user can set up which shipping data

elements and “tags” will be included in

the text. The tags <CR> will be replaced

with returns before writing text.

Shipment User Defined 1 - 5 Shipment tab User Field 1 - 5

(Original Format – for backwards

compatibility)

Shipment Field 1 – 5 Shipment tab Shipment Field 1


User Defined 1 - 5 Order Tab Order Field 1 - 5


compatibility)

Order Field 1 – 5 Order Tab Order Field 1 - 5



Charges

Freight charge after Freight Rules and

User-defined handling fee applied

Applied Charges Accessorial

Charges

Accessorial charges after Freight Rules

and User-defined handling fee applied


Fee

User-defined handling fee after Freight

Rules applied

Applied Charges Freight Cost Freight charge after Freight Rules and



Surcharge

Fuel Surcharge after Freight Rules and


Applied Charges Total Total Freight charges after Freight Rules

applied

List Charges Freight Charges Published rate Freight Charge





Charges

Published rate accessorial charges




Charges

Custom rate Freight Charges

Contract Charges Surcharges Custom rate surcharge

Contract Charges Discounts Custom rate discounts

Contract Charges Accessorial

Charges

Custom rate accessorial charges

eCommerceOrderNumber eCommerce Order Number

Item_###_999 Contains field values which are at the line item level. ### is the source document sequence number this line item belongs to. 999 is the Line Number.

Additional Name/value pairs may be present if Custom Write-Back fields are mapped. Custom Fields are defined in the Field List File.


Name Value

ItemNumber Item Number

ShipQty Ship Quantity

UOM Unit of Measure

Extra Key 1 – 3 If Extra Key was mapped on import, will be written back. Extra Keys allows for multiple line Items of the same Item Code to be imported separately.

User Defined 1 – 5 Line Item User Defined Fields 1 - 5


Item Field 1 - 5 Item Field 1 – 5



DeltaShipQty Change in ShipQty (When shipping against Same order multiple times or voiding it)

eCommerceItemNumber The key that identifies the line item in the eCommerce order, such as the ASIN, SKU, etc.

Package_### Following all Shipment sections, file will contain one section for each package in the shipment. ### is the Package sequence number. NOTE: This list is not complete and some fields may change:

Additional Name/value pairs may be present if Custom Write-Back fields are mapped. Custom Fields are defined in the Field List File.


Name Value

Package Number Sequential Package Number (1…n)

Package ID Index number for imported packages:

If Document file imported

contains Package ID field with a

valid value, the same value is

returned in the Shipment file.

Value has to be a positive integer.

For packages added manually by

user will always be -1.

Package Quantity One package entry can represent multiple

physical packages. For example, the user

can pack 25 widgets into two medium

boxes without specifying exactly how they

are distributed.

Packaging Packaging which displays on the Packaging

tab in the Package Info group.

Freight Class Freight class for this package (highest class

of items contained within)

Length Length of the package in inches

Height Height of the package in inches


Width Width of the package in inches

Calculated Weight Weight of the package calculated by

adding contents weight and the weight of

the packaging itself.

Actual Weight Same as Calculated Weight unless user

enters an overriding value

Packaging Weight Weight of the package itself

Package Content Package Contents Field from the Shipment for that package

Tracking Number Package Tracking Number

SSCC Container ID (SSCC) field in the Package group on the 'Packaging' tab.

Billed Weight Package Billed Weight (greatest of Dimensional Weight vs. Actual Weight)

Charges Total Applied Charges for backwards compatibility


User Defined 1 - 5 Package User Defined Fields 1 – 5


Pack Field 1 - 5 Pack Field 1 - 5


Reference 1 - 5 Carrier Reference Fields mapped to package user defined fields for this shipment. Will only be present if setup in Carrier settings.

COD Type COD Type

COD Amount COD Amount per package

Hazardous Y or N value indicating if package contained Hazardous Items


Handling Fee User-defined handling fee per package

Zone Delivery Zone


Charges Freight charge after Freight Rules and User-defined handling fee applied

Applied Charges Accessorial

Charges Accessorial charges after Freight Rules and User-defined handling fee applied


Fee User-defined handling fee after Freight Rules applied


Applied Charges Freight Cost Freight charge after Freight Rules and User-defined handling fee applied


Surcharge Fuel Surcharge after Freight Rules and User-defined handling fee applied

List Charges Freight Charges Published rate Freight Charge




Charges Published rate accessorial charges




Charges Custom rate Freight Charges

Contract Charges Surcharges Custom rate surcharge

Contract Charges Discounts Custom rate discounts

Contract Charges Accessorial

Charges Custom rate accessorial charges


Charges Custom rate miscellaneous charges


Contents_###_999 One or more contents entries are used to describe the contents of a package. ### is the Package sequence number this contents section belongs to. 999 is the contents sequence. Each Contents# entry should contain the following field/value pairs:

PackageNumber - must match a Package number above.

LineNumber- must match an Item Index for the DocumentKey above.

Package Content Sales Order – must match a DocumentKey or OrdNum key above (optional if only one document is included in the file)

Quantity – number of ItemNumber contained in PackageNumber

Extra Key1 – 3 – ExtraKey of the Item contained in Package

Unit_# Following all Shipment sections, file will contain one section for each handling unit in the shipment:

Name Value

Handling Unit Number Sequential Handling Unit Number (1…n)

Handling Unit ID StarShip Handling Unit ID (Same as

Handling Unit Number)

Handling Unit Internal ID Index number for Handling Units:

For Handling Units imported with

valid value in the “Handling Unit

ID” field of the Document file, the

value will be the same as what was

imported. Value has to be a

positive integer.

For Handling Units imported

without a “Handling Unit ID”, the

value will be the same as

“Handling Unit Number”

For Handling Units added manually

in StarShip, the value will always

be -1

Handling Unit Quantity One Handling Unit entry can represent

multiple physical pallets. For example, the

user can pack 10 boxes into two pallets

without specifying exactly how they are

distributed.


Handling Unit Packaging Packaging which displays on the Packaging

tab in the Package Info group.

Handling Unit Package Type Base type of Handling Unit on the

Packaging tab in the Package Info group

Handling Unit Freight Class Freight class for this Handling Unit (highest

class of Packages contained within)

Handling Unit Length Length of the Handling Unit in inches

Handling Unit Height Height of the Handling Unit in inches

Handling Unit Width Width of the Handling Unit in inches

Handling Unit Calculated

Weight

Weight of the Handling Unit calculated by

adding weight of contents and weight of

the Handling Unit itself.

Handling Unit Actual Weight Same as Calculated Weight unless user

enters an overriding value

Handling Unit Packaging

Weight

Weight of the Handling Unit itself

Zone Delivery Zone

SSCC Container ID (SSCC) field in the Handling

Unit group on the 'Packaging' tab.

License Plate License Plate

Handling Unit User Defined 1

- 5

Handling Unit User Defined Fields 1 – 5


compatibility)

Pallet Field 1 - 5 Pallet Field 1 - 5


Settings One Settings section will be included after all Package sections. Values under Settings flags tell integrated application how to handle information returned in shipment file:


Name Value

UpdateFreightFlag Y if User wants freight applied to source document(s).

UpdateTrackingFlag Y if User wants tracking information updated in source document(s).

Sample StarShip Shipment file in INI format:

[SHIPMENT_001]

OrdNum=2068

Status=Add

Shipment Number=1

ID=BOL:70886887

BOLNumber=70886887

PRONumber=

DeltaFreight=119.43

Freight=119.43

CODAmount=0.00

COD Freight Tax Amount=0.00

Declared Value=0.00

Weight=155.00

Service=LTL

SCAC=HMES

Carrier=Holland

ReadyDate=12/07/2015

Order Number=2068

Customer Number=XTOINC-01

PO Number=09-31

Department=

Freight Billing=S

Freight [email protected]

Applied Charges Freight Charges=238.86

Applied Charges Accessorial Charges=0.00

Applied Charges Handling Fee=0.00

Applied Charges Total=238.86

Applied Charges Freight Cost=238.86

Applied Charges Fuel Surcharge=0.00

List Charges Freight Charges=0.00

List Charges Surcharges=0.00

List Charges Discounts=0.00

List Charges Accessorial Charges=0.00

List Charges Misc Charges=0.00

List Charges Total=0.00

Contract Charges Freight Charges=205.81

Contract Charges Surcharges=33.05

Contract Charges Discounts=0.00

Contract Charges Accessorial Charges=0.00

Contract Charges Misc Charges=0.00

Contract Charges Total=238.86

Notes=Shipped on 12/7/2015<cr>----------------------------------------<cr>End Shipment(s)

DocumentType=Order

DocumentKey=2068

CarrierType=0

MasterTrackingID=70886887

COD Base Amount=0.00


Service Code=LTL

Delivery Date=12/08/2015

eCommerceOrderNumber=

Shipment ID=16

ReturnShipment=N

User ID=admin

Shipment User Defined 1=





User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Shipment Field 1=

Shipment Field 2=

Shipment Field 3=

Shipment Field 4=

Shipment Field 5=

Order Field 1=

Order Field 2=

Order Field 3=

Order Field 4=

Order Field 5=

InternalID=16

SHIP VIA=TRUCK

CUSTOMWB1=Leave at back door

[ITEM_001_001]

ItemNumber=CUSTOM_SEW1

UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=

eCommerceItemNumber=

DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_001_002]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=


Item Field 3=

Item Field 4=

Item Field 5=

[SHIPMENT_002]

OrdNum=2068

Status=Add

Shipment Number=2

ID=BOL:70886887

BOLNumber=70886887

PRONumber=

DeltaFreight=119.43

Freight=119.43

CODAmount=0.00


Declared Value=0.00

Weight=250.00

Service=LTL

SCAC=HMES

Carrier=Holland


Order Number=2067


PO Number=09-32

Department=

Freight Billing=S



DocumentType=Order

DocumentKey=2068

CarrierType=0



Service Code=LTL



Shipment ID=16

ReturnShipment=N

User ID=admin






User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Shipment Field 1=

Shipment Field 2=

Shipment Field 3=

Shipment Field 4=

Shipment Field 5=

Order Field 1=

Order Field 2=

Order Field 3=

Order Field 4=

Order Field 5=

InternalID=16

SHIP VIA=TRUCK


[ITEM_002_001]



UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=3

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_002_002]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_002_003]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[PACKAGE_001]

Zone=

Package ID=-1

Package Number=1

Package Quantity=1

Packaging=Custom Box

Freight Class=55

Length=0

Height=0


Width=0

Calculated Weight=155.00

Actual Weight=155.00

Packaging Weight=0.00

Package Content=SB GRNGARD 59FT X 83FT 2A 2B

Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=1

Actual Weight in UOM=155.00

Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000656

Package Type=Box

[CONTENT_001_001]

Package Content Quantity=2

Package Content UOM=EA

Package Content Item Number=CUSTOM_SEW1

Package Content Sales Order=2068

Package Content Extra Key1=



[CONTENT_001_002]









[PACKAGE_002]

Zone=

Package ID=-1

Package Number=2

Package Quantity=1


Freight Class=65

Length=0

Height=0

Width=0





Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=1


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000663

Package Type=Box

[CONTENT_002_001]









[CONTENT_002_002]








[CONTENT_002_003]








[PALLET_001]

Handling Unit ID=1

Handling Unit Internal ID=-1

Handling Unit Number=1

Handling Unit Quantity=1

Handling Unit Packaging=Custom Pallet

Handling Unit Freight Class=65

Handling Unit Length=0

Handling Unit Height=0

Handling Unit Width=0

Handling Unit Calculated Weight=405.00

Handling Unit Actual Weight=405.00

Handling Unit Packaging Weight=0.00

Handling Unit Actual Weight in UOM=405.00

Handling Unit Weight UOM=lbs

Zone=

SSCC=004000081000000625

License Plate=

Handling Unit Package Type=Pallet

Handling Unit User Defined 1=





Pallet Field 1=

Pallet Field 2=

Pallet Field 3=

Pallet Field 4=

Pallet Field 5=

[SETTINGS]

UpdateFreightFlag=Y

UpdateTrackingFlag=Y

3.4. Field List File

The Field List file provides the user with a complete list of all fields in the Document file for each supported

document type. This list helps the user to view and modify mappings. The field list must be in XML format.

Section Description


FSI_InputFields Root element which contains one or more FSIField elements.

FSIField Each FSIField element represents a single field in the integrated application. Contains child nodes that are properties of that field.

FSIField\FieldName Field name – must match the name of the field in the Document file.

FSIField\MapType Controls if this field is available for input mapping, custom Write-Back mapping or both. Possible values are:

Read – Only available for mapping input fields.

Write – Only available for mapping with Custom Write-Back.

ReadWrite –Available for both input mappings and for Write-Back setup.

Defaults to ‘Read’ if property not specified.

FSIField\Level Controls what level of StarShip field the Write-Back can be mapped to. Has no effect for input mappings.

Header – Only available for mapping with Custom Write Back.

Line – Only Line Item StarShip fields will be available.

Package –Only Package StarShip fields will be available.

Defaults to ‘Header’ if property not specified.

FSIField\WriteSupportedFor Only relevant for Fields that Support Custom Write-Back. For Developers Interface this should always be set to ‘Ship’. If omitted can allow users to make an invalid selection in Write-Back setup.

FSIFIeld\IsNumeric Contains “True” if this field is numeric and “False” if not numeric. This flag is used by freight rules.

FSIFIeld\HasValueList Contains “True” if a list of possible values is provided and “False if no value list is provided. If no lists are provide, a user can manually create a list in StarShip Customize Interface for those StarShip fields that are lists.

FSIField\Description Description of the field. Ideally this tells the user where they can see this field on the integrated application’s entry screen. For example “PO Number field on the Main tab of the Order Entry screen”

FSIField\FSI_InputValues If a Field has a finite list of possible values (i.e. fields represented as a drop-down box, radio group, or checkbox in the integrated application), then the FSI_InputValues element is used to specify those values. Providing this information is optional, but very useful when the user wants to customize the mappings of these field values to StarShip values. These input values are also available for Custom Write-Back mappings. This way you can send back a value recognized by the integrated application and avoid extra logic to translate the


StarShip values.

FSIField\FSI_InputValues\ FSIValue

Each FSI_InputValues element contains one or more FSIValue elements to enumerate the possible values for this field if it has a finite list of values. For example, Ship Via or Customer Type fields which may be represented as a drop-down box to the user. Also, Boolean flags such as “Residential Address” may be represented as a checkbox or radio box to the user and would have two values representing checked/unchecked.

Field List Example:

<FSI_InputFields>

<FSIField>

<FieldName>Sales Order Number</FieldName>

<IsNumeric>False</IsNumeric>

<HasValueList>False</HasValueList>

<Description>Sales Order Number on the Main tab of the Sales Order Entry

screen.</Description>

</FSIField>

<FSIField>

<FieldName>PO Number</FieldName>



<Description>PO Number on the Main tab of the Sales Order Entry screen</Description>

</FSIField>

<FSIField>

<FieldName>Ship Via</FieldName>

<MapType>ReadWrite</MapType>

<WriteSupportedFor>Ship</WriteSupportedFor>


<HasValueList>True</HasValueList>

<Description>Ship Via on the Ship To tab of the Sales Order Entry screen.</Description>

<FSI_InputValues>

<FSIValue Value="UPS Next Day" />

<FSIValue Value="FedEx Freight" />

<FSIValue Value="FedEx Standard" />

</FSI_InputValues>

</FSIField>

<FSIField>

<FieldName>Ship To Residential</FieldName>


<HasValueList>True</HasValueList>

<Description>Residential checkbox on the Ship To tab of the Sales Order Entry

screen.</Description>

<FSI_InputValues>

<FSIValue Value="Yes" />

<FSIValue Value="No" />

</FSI_InputValues>

</FSIField>

<FSIField>

<FieldName>Item Number</FieldName>



<Description>Item Number on Main tab of the Sales Order Entry screen.</Description>

</FSIField>

<FSIField>


<FieldName>CustomWB1</FieldName>

<MapType>Write</MapType>




<Description>Custom Write Back Field 1</Description>

</FSIField>

<FSIField>

<FieldName>Package CustomWB1</FieldName>

<MapType>Write</MapType>


<Level>Package</Level>



<Description>Package level Custom Write Back Field 1</Description>

</FSIField>

</FSI_InputFields>

3.5. Default Map File

A default map file is referenced in the configuration file for each document type. It can be created from within

the StarShip Customize interface screen as follows:

1. The developer can send in a Document file without any mapping.

2. The Customize Interface screen will automatically display.

3. The developer can set up the mapping to StarShip fields in a way that can be used by most users.

4. The developer presses the control key: Ctrl - Shift - F6 to save the current mappings to a file.

5. Repeat steps 1-4 for each document type, saving the XML mappings to a different name.

Once this is done, the developer can distribute the default mapping files and configuration file with their

interface. The Default Map file also supports mappings and Value Translations configured for Custom Write-

Back.

3.6. Error Message File

The Error Message file is used to send error messages from the integrated application to StarShip. One example

would be a “Document not found” message when StarShip sends a request for a financial system document that

does not exist. The Error Message File is the Document file, and can be in INI or XML format.

Sample Error Message file in INI format:

Section Description

Error This section contains one or more lines of text to display in the error message.

[ERROR]


Document not found.

Verify and re-enter…

The error message can consist of multiple lines

Sample Error Message file in XML Format:

In XML format, the sections are XML elements.

Section Description

SelectResult Root node

ErrorMsg Contains the text of the message, as well as some HTML tags (for formatting)

<SelectResult>

<ErrorMsg><Font color=blue>Error Message here</Font> <br> <B>FSI <I>document</I> not

found</B></ErrorMsg>

</SelectResult

4. Monitoring for StarShip Request and Shipment Files

The following strategies can be used by the integrated application when waiting for input from StarShip:

4.1. Polling

The integrated application can use a timer to periodically check for the existence of a new input file from StarShip.

4.2. Windows Change Notification

The integrated application can configure itself to receive windows notifications when changes occur in the

StarShip Output path. Please refer to the following MSDN articles for details:

SHChangeNotifyRegister Function - http://msdn.microsoft.com/en-us/library/bb762120.aspx

SHChangeNotifyDeregister Function - http://msdn.microsoft.com/en-us/library/bb762119(VS.85).aspx

SHChangeNotifyEntry - http://msdn.microsoft.com/en-us/library/aa931819.aspx

Sequence:

Call OpenNotification, pass in the window handle and path to be monitored, save a handle to this notification

In WindowProc associated with this window handle check for Msg=WM_SHELLNOTIFY, it will be posted to this

handle every time a file in this folder is created/modified/deleted.

Finally, call SHChangeNotifyDeregister( hNotify ).

Sample Code

http://msdn.microsoft.com/en-us/library/bb762120.aspx

http://msdn.microsoft.com/en-us/library/bb762119(VS.85).aspx

http://msdn.microsoft.com/en-us/library/aa931819.aspx


Const WM_SHELLNOTIFY = WM_USER + 2;

function OpenNotification( hWindow : HWND; sPath : String ) : ULONG;

var

BuffPath : Array[0..MAX_PATH] of WideChar;

cEntries : Integer;

fEvents : Longint;

Attr : PDWORD;

NotifyEntry : SHChangeNotifyEntry;

begin

fEvents := SHCNE_ALLEVENTS;

cEntries := 1;

if Win32Platform <> VER_PLATFORM_WIN32_WINDOWS then begin

StringToWideChar(sPath, BuffPath, SizeOf(BuffPath));

if ( SHILCreateFromPathNT(BuffPath, @NotifyEntry, Attr ) <> S_OK )

then RaiseLastOsError;

end else begin

if ( SHILCreateFromPath(PChar( sPath ), @NotifyEntry, Attr) <> S_OK )

then RaiseLastOsError;

end;

NotifyEntry.fRecursive := FALSE;

Result := SHChangeNotifyRegister( hWindow,

SHCNF_ACCEPT_INTERRUPTS + SHCNF_ACCEPT_NON_INTERRUPTS,

fEvents,

WM_SHELLNOTIFY,

cEntries,

@NotifyEntry );

end;

4.3. Windows Messages

Support for Windows Messages is provided for backwards compatibility with StarShip 9.x interfaces. It is not

recommended for use when developing new interfaces because of possible issues in Windows Vista.

When the configuration file header section has the Broadcast Message value set to “Y”, then StarShip and the

integrated application register a message using the string “SHIPADE”. When either program writes a file, they

broadcast the registered message. When expecting an input file, they wait for the message. The message sent

does not contain any information, but simply indicates that the input file is available.

Note: to broadcast the message, use the SendMessageTimeOut, instead of SendMessage which will not return if

any currently open window is unable to handle the message.

5. User Setup and Customization

The developer interface is designed so that the user has minimal steps to get the interface operable, and still

provides them a means of customizing it to their specific needs.

5.1. Setup

To set up the integration, the StarShip user points to a configuration file, which is created and updated

dynamically by the integrated application (see section 2).


If the integrated application is using the default location and file name (%AllUsersProfile%\Application Data\V-

Technologies\StarShip Interface\Configuration.XML – or Configuration.INI) then the user does not have to

perform this step.

If not using the default location, then the user performs the following steps:

1. Setup > Financial System Interface > My Interface.

2. Click on “My Companies” on the left side of the screen and browse to the configuration file.

3. The list of companies will be populated.

Once the configuration file is specified, “My Interface” will be replaced with the actual interface name if it is

included in the configuration file. This name is used on the Setup menu items, Setup screens, and on the Shipping

screen for the Source prompts.

5.2. Customize Interface

StarShip allows the user to set up an “interface” which can be assigned to one or more companies in their

integrated application. The interface consists of:

Field mappings which define how fields from the input document will be read into shipment fields.

Translations are used for shipment fields that have a finite set of values (such as Carrier, Package Type,

and flags such as Hazardous Materials). A translation defines how the text value in the input document is

converted to a valid value in StarShip.

Settings for writing back to the source document which enable/disable freight and define the contents of

notes (a text string containing tracking information).

T o minimize the setup required by the user, one interface called “My Interface” is automatically created. It uses

the default map which is provided in the configuration file. Also, translations will be done using key words if the

user has not yet defined them.

The user can create and modify interfaces from the Customize Interface screen in StarShip by selecting Setup >

Financial System Interface > {interface name}. The actual interface name will be specified in the configuration file

(see section 2).

The user clicks on Customize Interface on the left side of the screen to view a list of currently defined interfaces.

Under each interface is a list of documents supported (defined in the configuration file). The user can modify “My

Interface” or create a new interface.

When the user clicks on a document, the Customize Interface screen appears:

On the left side is a list of StarShip field groups organized in a tree view. If you click on any folder under

Target Fields, the list of fields shows in the center panel.


If you click on a specific field in the center panel, the current mapping shows on the right side. The

mapping can be none, fixed value, or to a field in the source document.

If a target field has a fixed set of values (such as Carrier, Packaging, or Hazardous Materials (Select) and

that field is mapped to the source document, the link “Click here to update value translations” will appear

on the right panel. Clicking on this link allows the user to view and modify the translations.

From Write-Back Setup the user can

o Click Freight Settings to enable or disable freight write-back. The flags set here will be returned in

the StarShip Shipment file Settings section (see section 3.3)

o Click Notes Settings to enable or disable notes write-back. The checkbox to enable/disable notes

write-back is returned in the Settings section of the StarShip Shipment file. If enabled, the user

selects shipment fields to be formatted as text and returned in the TrackingInfo (Notes for INI

format) section of the StarShip Shipment file.

o Click on Custom Fields to setup custom write back. The fields available for custom Write-Back

mappings and the levels they are on are defined in the Field List File (see Section 5.3 and 3.3).

Once mapped, those fields and the shipment values they are mapped to will be present in the

Shipment file.

Once the user has modified or created an interface, they can define which companies in the integrated

application will use which interface by clicking on My Companies on the left side of the screen.

5.3. Custom Write-Back

StarShip (version 15.3 and higher) allows extending the fields that are written back by default (documented in

Section 3.3). You can define new fields and map what StarShip Shipment values will be passed back in those

fields. The integrated application has to be made to recognize those new fields as well.

The Field List File controls what fields are available for Custom Write-Back by the ‘MapType’ property (see section

3.4). Once a field has been flagged as available for Custom Write Back, it will be become visible in the Write-Back

section of Customize Interface (see section 5.2). Value translations can also be set to translate StarShip field

values to values recognized by the Integrated Application.

When mapped to Write-Back, the field will appear in the Shipment file at the specified level. For XML formatted

Shipment Files, the custom Write-Back fields will have a ValueType attribute of ‘Source’. Standard Write-Back

fields now have a ValueType of ‘Shipment’ to distinguish them from custom Write-Back fields for XML. INI

formatted files will just have the new field present with the StarShip shipment value.

6. The Shipping Process

The shipping process differs depending on the StarShip Mode which is defined in the configuration File (see

section 2). StarShip can be the Requestor (i.e. initiates the shipment) or the Responder (i.e. responds to requests

from the integrated application).


Whichever mode is used, the process is sequential. When a request file is sent, the requestor will wait until the

response file is returned before continuing. StarShip will always delete the files it receives after reading them.

Files that are received by the integrated application will be handled (deleted or archived) as determined by the

developer of that application.

Example of File Handling with StarShip as Requestor

StarShip creates the request file – “MACHINE-A.USER-A.REQ” o The user will have the ability to cancel the request – only as long as the request file has not been

picked up/deleted by the Integrator service. If the request is cancelled, StarShip will delete the request file and the user can initiate a

different request

Integrator service picks up the file, creates the FSI Document file – “MACHINE-A.USER-A.FSIDOC” o Integrator service will delete the request file at this time o If the requested document is not found, the Integrator service will send the FSI Document file as

Error Message file (see section 3.6)

StarShip reads the FSI Document file – “MACHINE-A.USER-A. FSIDOC” o StarShip deletes the FSI Document file at this time

After the user processes the shipment, StarShip creates the StarShip Shipment file – “MACHINE-A.USER-A.SHIPDOC”

Integrator service picks up the file, and updates the Financial System o Integrator service will delete the shipment file at this time

6.1. StarShip as Responder

A shipment will be processed as follows when StarShip is the Responder:

1. The user runs StarShip and it begins monitoring the StarShip Input Path for files which match the Input

File Name Mask (both set in the configuration file as defined in section 2).

2. The user brings up a document in the integrated application and initiates the shipping function (i.e.

presses a button, hot key, menu item). The integrated application writes a Document file (see section 3.2)

to the StarShip Input Path using a name compatible with the Input File Name Mask.

3. StarShip detects the document file and reads it.

a. Based on the Company and Document Type, it looks for an interface (mappings and translations

which can be set by the user).

b. If no interface is found, Starship will load the default map as specified in the Configuration file.

c. If no default map is found, StarShip will bring up the Customize Interface screen to allow the user

to set the mapping.

4. StarShip converts the input document to a shipment based on the mappings and translations (see section

5).


a. If an open (not yet booked) StarShip shipment already exists for the input company, document

type, and document number, the user will be asked if they want to bring up the existing shipment

or create a new one.

b. If an existing shipment is opened, new input will be merged.

5. The user can modify the shipment as desired. They may need to add information such as packaging if not

provided in the input document. The user will typically click the Rate Shipment button to get rates. The

user can then do one of three things:

a. Click “Ship / Process” to book the shipment, save it, and print documentation. StarShip writes the

“Add” response to the StarShip Shipment file (see section 3.3) using the Output File Name and

StarShip Output Path specified in the configuration file. StarShip will minimize and wait for input.

b. Click “Return Quote” if they are not ready to book the shipment but want to send freight charges

back to the integrated application. StarShip writes the “Quote” response to the StarShip

Shipment file (see section 3.3) using the Output File Name and StarShip Output Path specified in

the configuration file. StarShip will minimize and wait for input. Note: the shipment will not be

saved in StarShip unless the user clicks the “Save” button prior to “Return Quote”.

c. Click “New” or close StarShip to cancel processing. StarShip writes a “Cancel” response to the

StarShip Shipment file (see section 3.3). If the user clicks “New”, StarShip will minimize and wait

for input.

6. The integrated application will read the StarShip Shipment file written to the StarShip Output Path (see

section 4 for possible strategies). The StarShip Shipment file contents may contain a “Cancel”, “Quote”,

or “Add” response. If “Quote” or “Add” the complete shipment will be returned and the application can

read the freight charges and packaging. If “Add” the application can also read tracking information (BOL

number, PRO number, Tracking Numbers).

6.2. StarShip as Requestor

A shipment will be processed as follows when StarShip is the Requestor:

1. The user runs StarShip and selects a Company and Document type from the Source area of the shipping

screen.

2. The user enters a document number in the first entry box of the Source area (will be labeled with the

interface name and document type) and presses Enter. StarShip writes a StarShip Request File (see

section 3.1) to the StarShip Output path with the company, document type, and document number.

3. The integrated application detects the request (see section 4 for possible strategies) and responds by

writing a Document file (see section 3.2) to the StarShip Input Path using a name compatible with the

Input File Name Mask.

4. StarShip detects the document file and reads it.


a. Based on the Company and Document Type, it looks for an interface (mappings and translations

which can be set by the user).

b. If no interface is found, Starship will load the default map as specified in the Configuration file.

c. If no default map is found, StarShip will bring up the Customize Interface screen to allow the user

to set the mapping.

5. StarShip converts the input document to a shipment based on the mappings and translations (see section

5).

a. If an open (not yet booked) StarShip shipment already exists for the input company, document

type, and document number, the user will be asked if they want to bring up the existing shipment

or create a new one.

b. If an existing shipment is opened, new input will be merged.

6. The user can modify the shipment as desired. They may need to add information such as packaging if not

provided in the input document. The user will typically click the Rate Shipment button to get rates. The

user can then do one of three things:

a. Click “Ship / Process” to book the shipment, save it, and print documentation. StarShip writes the

“Add” response to the StarShip Shipment file (see section 3.3) using the Output File Name and

StarShip Output Path specified in the configuration file.

b. Click “Return Quote” if they are not ready to book the shipment but want to send freight charges

back to the integrated application. StarShip writes the “Quote” response to the StarShip

Shipment file (see section 3.3) using the Output File Name and StarShip Output Path specified in

the configuration file. Note: the shipment will not be saved in StarShip unless the user clicks the

“Save” button prior to “Return Quote”.

c. Click “New”, enter a new document, or close StarShip to cancel processing. StarShip writes a

“Cancel” response to the StarShip Shipment file (see section 3.3).

7. The integrated application will read the StarShip Shipment file written to the StarShip Output Path (see

section 4 for possible strategies). The StarShip Shipment file contents may contain a “Cancel”, “Quote”,

or “Add” response. If “Quote” or “Add” the complete shipment will be returned and the application can

read the freight charges and packaging. If “Add” the application can also read tracking information (BOL

number, PRO number, Tracking Numbers).

7. StarShip 9.x Backwards Compatibility

The StarShip 10 developer interface has been designed to be backwards compatible with the StarShip 9 “ADE” and

StarShip Server interfaces. We also now provide an ADE Interface specifically designed for 99x backwards

compatibility that also supports 99x interfaces that had special handling. See section 7.2 for more information.


7.1. Configuration File

1. %StarShip9Station% variable can be used for the Input File Name Mask field. If the 99x Starship.ini file is

present the 99x station number specified will be used for this variable. This would mostly be used to

support Terminal Server/Citrix Environments so that StarShip can distinguish between different station’s

inputs.

If an environmental variable exists on the machine with the same name, it will be used instead of the

StarShip.ini file.

2. “Version 9 Compatible” flag. If this flag is set equal to ‘Y’ then StarShip will use the 99x ADE field names in

the shipment file that is written back. The 99x fields will be listed first, with the new StarShip 10 fields

following. The 99x field names are listed in the chart below and are also available in the 99x

documentation: http://www.vtechnologies.com/webhelp/ss/communication_protocol.htm.

This flag is only applicable for INI formatted configuration and Shipment files.

99x Field Names:

Name Value

OrdNum Order Number

Status Save - means user clicked “Ship /

Process” button

Update- means order is reprocessed in

StarShip

Quote - means user clicked “Return

Quote” button

Delete - means user clicked “Void

Shipment” button

TotFreight Total freight charges

TotCharges Total Freight charges after Freight Rules applied

TotHFee User-defined handling fee

TotCODAmt Total shipment COD Amount

TotDValue Total Declared Value option amount

TotWeight Total shipment weight

TotPkgs Shipment total packages

http://www.vtechnologies.com/webhelp/ss/communication_protocol.htm


TaxAmt Freight Tax amount

TotScaleWeight Total Weight from scale

USERFIELD1 Order Tab Order Field 1






TotBillSender Total amount billed to sender

7.2. StarShip 9.x ADE special cases:

1. For Businessworks, the shared path defaults to program path in BWUser.ini file (in current user’s

application data folder under \Sage\SageBusinessWorks). Also, there are settings which user can set in

StarShip and are stored in BWUser.ini to tell BW how to read the freight fields from ADE_OUT.

2. For Eclipse (running on Unix), we can specify a separate input and output path.

3. The file names used are always ADE_IN.# (input to StarShip) and ADE_OUT.# (output from StarShip)

where # is the StarShip station number (0-99).

7.3. Integrate StarShip 10 with a StarShip 9.x compatible Application

If a user wants to integrate StarShip 10 with an application such as BusinessWorks, Starship 10 will provide the

following settings:

1. Integrate to a StarShip 9.x compatible application Y/N

2. What is the name of the application? (Allow user to type a name or choose from drop-down list of known

interfaces: BusinessWorks, Eclipse, Southware, etc.) If a known interface, can skip remaining settings.

3. Is StarShip the Requestor or Responder?

4. Broadcast Windows Message when file is available Y/N?

5. If StarShip is the Responder, then allow user to enter the shared path and station number. Store these in

%windir%\starship.ini

6. There will be a setting added to have StarShip use 9.x ADE format for the shipment file that is sent back to

the integrated application.


Configuration files for all known existing ADE interfaces are distributed, and point to pre-defined field lists and

default maps.

8. Appendix A – Sample Transactions

Sample transactions are also available in XML and INI file formats distributed in a zip file, along with this

document (StarShip Developer Interface.pdf). Please note that the sample document files require the field list and

maps that are included in order to work properly. Also included are samples of the StarShip Shipment file for each

document submitted.

8.1 Sample Single Order - XML

Sample Document:

<SelectResult>


<Header>

























</Header>

<LineItems>









</LineItem>










</LineItem>

</LineItems>

</Document>

</SelectResult>

Sample Shipment Response:


<WriteShipment>




<FreightInfo>

<Shipment>

<Sender ID="" NAME="Dewitt - Play" CONTACT="" ADDRESS1="905 South Kingshighway" ADDRESS2=""

ADDRESS3="" CITY="Sikeston" STATE="MO" ZIP="63801" COUNTRY="US" PHONE="5734720048" EMAIL=""


<Recipient ID="XTOINC-01" NAME="LAKE LANIER ISLAND RESORT" CONTACT="" ADDRESS1="EMERALD

POINTE GOLF CLUB" ADDRESS2="7000 HOLIDAY ROAD" ADDRESS3="" CITY="BUFORD - LAKE LANIER ISLAND"

STATE="GA" ZIP="30518" COUNTRY="US" PHONE="2567662091" EMAIL="" RESIDENTIAL="False"/>

<BillTo ID="FQ" NAME="Freightquote.com" CONTACT="" ADDRESS1="16025 W 113th St" ADDRESS2=""

ADDRESS3="" CITY="Lenexa" STATE="KS" ZIP="66219" COUNTRY="US" PHONE="8003235441" EMAIL=""






<NameValue Name="MasterTrackingID" Value="70874035" ValueType="Shipment"/>





<NameValue Name="COD Freight Tax Amount" Value="0.00" ValueType="Shipment"/>

<NameValue Name="COD Base Amount" Value="0.00" ValueType="Shipment"/>





<NameValue Name="SCAC" Value="HMES" ValueType="Shipment"/>

<NameValue Name="Carrier" Value="Holland" ValueType="Shipment"/>

<NameValue Name="ReadyDate" Value="12/07/2015" ValueType="Shipment"/>

<NameValue Name="Delivery Date" Value="12/08/2015" ValueType="Shipment"/>


<NameValue Name="eCommerceOrderNumber" Value="" ValueType="Shipment"/>

<NameValue Name="Customer Number" Value="XTOINC-01" ValueType="Shipment"/>






<NameValue Name="Freight Account" Value="[email protected]" ValueType="Shipment"/>


<NameValue Name="Shipment User Defined 1" Value="" ValueType="Shipment"/>






















<NameValue Name="Applied Charges Freight Charges" Value="247.86" ValueType="Shipment"/>

<NameValue Name="Applied Charges Accessorial Charges" Value="0.00" ValueType="Shipment"/>

<NameValue Name="Applied Charges Handling Fee" Value="0.00" ValueType="Shipment"/>

<NameValue Name="Applied Charges Total" Value="247.86" ValueType="Shipment"/>

<NameValue Name="Applied Charges Freight Cost" Value="247.86" ValueType="Shipment"/>

<NameValue Name="Applied Charges Fuel Surcharge" Value="0.00" ValueType="Shipment"/>

<NameValue Name="List Charges Freight Charges" Value="0.00" ValueType="Shipment"/>

<NameValue Name="List Charges Surcharges" Value="0.00" ValueType="Shipment"/>

<NameValue Name="List Charges Discounts" Value="0.00" ValueType="Shipment"/>

<NameValue Name="List Charges Accessorial Charges" Value="0.00" ValueType="Shipment"/>

<NameValue Name="List Charges Misc Charges" Value="0.00" ValueType="Shipment"/>

<NameValue Name="List Charges Total" Value="0.00" ValueType="Shipment"/>

<NameValue Name="Contract Charges Freight Charges" Value="213.66" ValueType="Shipment"/>

<NameValue Name="Contract Charges Surcharges" Value="34.20" ValueType="Shipment"/>

<NameValue Name="Contract Charges Discounts" Value="0.00" ValueType="Shipment"/>

<NameValue Name="Contract Charges Accessorial Charges" Value="0.00" ValueType="Shipment"/>

<NameValue Name="Contract Charges Misc Charges" Value="0.00" ValueType="Shipment"/>

<NameValue Name="Contract Charges Total" Value="247.86" ValueType="Shipment"/>


<NameValue Name="CUSTOMWB1" Value="Leave at back door" ValueType="Source"/>

</Shipment>

</FreightInfo>

End Shipment(s)" StartDelimiter="Shipped

on 12/7/2015

<OrderItems>

<OrderItem>

<NameValue Name="ItemNumber" Value="CUSTOM_SEW1" ValueType="Shipment"/>





<NameValue Name="eCommerceItemNumber" Value="" ValueType="Shipment"/>












</OrderItem>

<OrderItem>



















</OrderItem>

</OrderItems>

</SourceDocument>

<BatchName/>

<Settings>



</Settings>

<Packaging>

<Package>















<Row Name="Package Content" Value="SB GRNGARD 62FT X 75FT 1A 1B" ValueType="Shipment"/>














<Row Name="Freight Account" Value="[email protected]" ValueType="Shipment"/>















</HandlingUnit>

</HandlingUnits>

</WriteShipment>

8.2 Sample Multiple-Order - XML

Sample Document:

<SelectResult>


<Header>

























</Header>

<LineItems>









</LineItem>










</LineItem>

</LineItems>

</Document>


<Header>

























</Header>

<LineItems>









</LineItem>









</LineItem>









</LineItem>

</LineItems>

</Document>


</SelectResult>



<WriteShipment>




<FreightInfo>

<Shipment>


























<NameValue Name="Carrier" Value="Dayton Freight Lines" ValueType="Shipment"/>























































</Shipment>

</FreightInfo>

End Shipment(s)"


<OrderItems>

<OrderItem>


















</OrderItem>

<OrderItem>



















</OrderItem>

</OrderItems>

</SourceDocument>




<FreightInfo>

<Shipment>


























<NameValue Name="Carrier" Value="Dayton Freight Lines" ValueType="Shipment"/>





































</Shipment>

</FreightInfo>

End Shipment(s)"


<OrderItems>

<OrderItem>


















</OrderItem>

<OrderItem>


















</OrderItem>

<OrderItem>



















</OrderItem>

</OrderItems>

</SourceDocument>

<BatchName/>

<Settings>



</Settings>

<Packaging>

<Package>





































</Contents>

</PackageContents>

</Package>

</Packaging>

<HandlingUnits>

<HandlingUnit>





























</HandlingUnit>

</HandlingUnits>

</WriteShipment>

8.3 Sample Customer Document - XML

Sample Document:

<SelectResult>

<Document DocumentType="Customer" DocumentKey="AAACO">

<Header>

<Row FieldName="Cust No." Value="AAACO"/>

<Row FieldName="Ship To Name" Value="AAA Company"/>

<Row FieldName="Terms" Value="NET10"/>

<Row FieldName="Ship To Address Line 1" Value="10501 San Pedro Avenue"/>

<Row FieldName="Ship To Address Line 2" Value=""/>

<Row FieldName="Ship To City" Value="San Antonio"/>

<Row FieldName="Ship To Contact Name" Value="SHIP2 Addr Contact"/>

<Row FieldName="Ship To Phone" Value="80055512557800"/>

<Row FieldName="Ship Via" Value="ROADWAY"/>

<Row FieldName="Ship To State" Value="TX"/>


<Row FieldName="Company Name" Value="My Test Company"/>

<Row FieldName="Company Contact person" Value="James Cray"/>

<Row FieldName="Company Address 1" Value="1234 West Oak Parkway"/>



<Row Name="Applied Charges Handling Fee" Value="0.00"/>

<Row Name="Applied Charges Total" Value="7.79"/>

<Row Name="Applied Charges Freight Cost" Value="7.79"/>

<Row Name="Applied Charges Fuel Surcharge" Value="0.00"/>

<Row Name="List Charges Freight Charges" Value="7.79"/>

<Row Name="List Charges Surcharges" Value="0.00"/>

<Row Name="List Charges Discounts" Value="0.00"/>

<Row Name="List Charges Accessorial Charges" Value="0.00"/>

<Row Name="List Charges Misc Charges" Value="0.00"/>

<Row Name="List Charges Total" Value="7.79"/>

<Row Name="Contract Charges Freight Charges" Value="7.79"/>

<Row Name="Contract Charges Surcharges" Value="0.00"/>

<Row Name="Contract Charges Discounts" Value="0.00"/>

<Row Name="Contract Charges Accessorial Charges" Value="0.00"/>

<Row Name="Contract Charges Misc Charges" Value="0.00"/>

<Row Name="Contract Charges Total" Value="7.79"/>

</Package>

</Packaging>

</WriteShipment>

8.4 Sample Document with Packaging - XML

Sample Document:

<SelectResult>

<Document DocumentType="Shipment" DocumentKey="62" Company="Sample Retail Company">

<Header>


<Row FieldName="Cust No." Value="JBT01"/>

<Row FieldName="Ship To Name" Value="Joe's Bike Tours"/>

<Row FieldName="Ship To Contact Name" Value="Joe Smith"/>

<Row FieldName="Ship To Address Line 1" Value="1 Lost Way"/>

<Row FieldName="Ship To Address Line 2" Value=""/>

<Row FieldName="Ship To City" Value="San Francisco"/>

<Row FieldName="Ship To State" Value="CA"/>


<Row FieldName="Ship To Phone" Value="1234567890"/>

<Row FieldName="Terms" Value="NET30"/>

<Row FieldName="PO Number" Value=""/>

</Header>

<LineItems>


<Row FieldName="Item No." Value="MBBA01"/>


<Row FieldName="Item Description" Value="Bike Assy"/>

<Row FieldName="Ordered Units" Value="1.000"/>



<Row FieldName="Units To Ship" Value="1.000"/>


</LineItem>




<Row FieldName="Item Description" Value="Handlebars"/>







</LineItem>




<Row FieldName="Item Description" Value="Brakes"/>






</LineItem>

</LineItems>

</Document>

<Packaging>

<Package>

<Row FieldName="Package Number" Value="0001"/>

<Row FieldName="Package Weight" Value="30.000"/>

<Row FieldName="Package Comment" Value="Bike Frame in here"/>

<Row FieldName="Handling Unit ID" Value="1"/>

<PackageContents>

<Contents>

<Row FieldName="Package Content Item Number" Value="MBBA01"/>

<Row FieldName="Package Content Item Quantity" Value="1"/>

<Row FieldName="Package Content Order Number" Value="62"/>

</Contents>

</PackageContents>

</Package>

<Package>

<Row FieldName="Package Number" Value="0002"/>

<Row FieldName="Package Weight" Value="35.000"/>

<Row FieldName="Package Comment" Value="Handlebar and brakes in here"/>

<Row FieldName="Handling Unit ID" Value="2"/>

<PackageContents>

<Contents>




</Contents>

<Contents>




</Contents>

</PackageContents>

</Package>

</Packaging>

<HandlingUnits>

<HandlingUnit>

<Row FieldName="Handling Unit ID" Value="1" />

<Row FieldName="Handling Unit Pallet Type" Value="Pallets" />

</HandlingUnit>

<HandlingUnit>

<Row FieldName="Handling Unit ID" Value="2" />

<Row FieldName="Handling Unit Pallet Type" Value="Pallets" />

</HandlingUnit>


</HandlingUnits>

</SelectResult>



<WriteShipment>


DocType="Shipment" DocumentType="Shipment" SourceCompanyName="Sample Retail Company" SourceID="94"


<FreightInfo>

<Shipment>

<Sender ID="MAIN" NAME="V-Technologies" CONTACT="Eric Brown" ADDRESS1="10 McKee Pl"

ADDRESS2="" ADDRESS3="" CITY="Cheshire" STATE="CT" ZIP="06410" COUNTRY="US" PHONE="2031235647"

EMAIL="[email protected]" RESIDENTIAL="False"/>

<Recipient ID="JBT01" NAME="Joe's Bike Tours" CONTACT="Joe Smith" ADDRESS1="1 Lost Way"

ADDRESS2="" ADDRESS3="" CITY="San Francisco" STATE="CA" ZIP="45322" COUNTRY="US"




















<NameValue Name="SCAC" Value="NPME" ValueType="Shipment"/>

<NameValue Name="Carrier" Value="New Penn Motor Express" ValueType="Shipment"/>





<NameValue Name="Customer Number" Value="JBT01" ValueType="Shipment"/>

<NameValue Name="PO Number" Value="" ValueType="Shipment"/>





























<NameValue Name="DocumentKey" Value="62" ValueType="Shipment"/>



















<NameValue Name="SHIP TO ADDRESS LINE 1" Value="1 Lost Way" ValueType="Source"/>

<NameValue Name="SHIP VIA" Value="FEDEX" ValueType="Source"/>

</Shipment>

</FreightInfo>

End Shipment(s)"


<OrderItems>

<OrderItem>

<NameValue Name="ItemNumber" Value="MBBA01" ValueType="Shipment"/>

















</OrderItem>

<OrderItem>



















</OrderItem>

<OrderItem>


















</OrderItem>

</OrderItems>

</SourceDocument>

<BatchName/>

<Settings>



</Settings>

<Packaging>

<Package>

<Row Name="Package ID" Value="0" ValueType="Shipment"/>














<Row Name="Package Content" Value="Bike Assy" ValueType="Shipment"/>







</PackageContents>

</Package>

</Packaging>

<HandlingUnits>

<HandlingUnit>


<Row Name="Handling Unit Internal ID" Value="1" ValueType="Shipment"/>




























</HandlingUnit>

<HandlingUnit>































</HandlingUnit>

</HandlingUnits>

</WriteShipment>

8.5 Sample Single Order – INI

Sample Document:

[Document]

DocumentKey=2066


DocumentType=Orders

Cust No.=XTOINC-01

Order No.=2066

PO Number=09-31






Ship To Zip=30518

Ship To State=GA

Order Total=1723.78

Ship Via=TRUCK

Terms=1.5% -10 - 30



Company Address 2=


Company State=MO







[Item1]




Ordered Units=2


Unit Weight=45

Item UOM=EA

[Item2]




Ordered Units=2


Unit Weight=32.5

Item UOM=EA



[SHIPMENT_001]

OrdNum=2066

Status=Add

Shipment Number=1

ID=BOL:70886760

BOLNumber=70886760

PRONumber=

DeltaFreight=169.77

Freight=169.77

CODAmount=0.00


Declared Value=0.00

Weight=155.00

Service=LTL

SCAC=AVRT

Carrier=Averitt Express


Order Number=2066


PO Number=09-31

Department=

Freight Billing=S





















DocumentType=Order

DocumentKey=2066

CarrierType=0



Service Code=LTL



Shipment ID=15

ReturnShipment=N

User ID=admin






User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=


User Defined 5=

Shipment Field 1=

Shipment Field 2=

Shipment Field 3=

Shipment Field 4=

Shipment Field 5=

Order Field 1=

Order Field 2=

Order Field 3=

Order Field 4=

Order Field 5=

InternalID=15

SHIP VIA=TRUCK


[ITEM_001_001]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_001_002]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[PACKAGE_001]

Zone=

Package ID=-1

Package Number=1

Package Quantity=1


Freight Class=50

Length=0

Height=0

Width=0


Actual Weight=90.00




Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=1


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000601

Package Type=Box

[CONTENT_001_001]








[PACKAGE_002]

Zone=

Package ID=-1

Package Number=2

Package Quantity=1


Freight Class=55

Length=0

Height=0

Width=0



Actual Weight=65.00



Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=1


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000618

Package Type=Box

[CONTENT_002_001]








[PALLET_001]

Handling Unit ID=1















Zone=

SSCC=004000081000000595

License Plate=







Pallet Field 1=

Pallet Field 2=

Pallet Field 3=

Pallet Field 4=

Pallet Field 5=

[SETTINGS]

UpdateFreightFlag=Y


8.6 Sample Multiple Order – INI

Sample Document:

[Document1]

DocumentKey=2066


DocumentType=Orders

Cust No.=XTOINC-01

Order No.=2066

PO Number=09-31






Ship To Zip=30518

Ship To State=GA

Order Total=1723.78

Ship Via=TRUCK

Terms=1.5% -10 - 30



Company Address 2=


Company State=MO







[Item1_1]





Ordered Units=2


Unit Weight=45

Item UOM=EA

[Item1_2]




Ordered Units=2


Unit Weight=32.5

Item UOM=EA

[Document2]

DocumentKey=2067


DocumentType=Orders

Cust No.=XTOINC-01

Order No.=2067

PO Number=09-32






Ship To Zip=30518

Ship To State=GA

Order Total=2832.64

Ship Via=TRUCK

Terms=1.5% -10 - 30



Company Address 2=


Company State=MO







[Item2_1]




Ordered Units=3


Unit Weight=45

Item UOM=EA

[Item2_2]




Ordered Units=2


Unit Weight=32.5

Item UOM=EA

[Item2_3]





Ordered Units=2


Unit Weight=25

Item UOM=EA


[SHIPMENT_001]

OrdNum=2068

Status=Add

Shipment Number=1

ID=BOL:70886887

BOLNumber=70886887

PRONumber=

DeltaFreight=119.43

Freight=119.43

CODAmount=0.00


Declared Value=0.00

Weight=155.00

Service=LTL

SCAC=HMES

Carrier=Holland


Order Number=2068


PO Number=09-31

Department=

Freight Billing=S





















DocumentType=Order

DocumentKey=2068

CarrierType=0



Service Code=LTL



Shipment ID=16


ReturnShipment=N

User ID=admin






User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Shipment Field 1=

Shipment Field 2=

Shipment Field 3=

Shipment Field 4=

Shipment Field 5=

Order Field 1=

Order Field 2=

Order Field 3=

Order Field 4=

Order Field 5=

InternalID=16

SHIP VIA=TRUCK


[ITEM_001_001]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_001_002]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[SHIPMENT_002]


OrdNum=2068

Status=Add

Shipment Number=2

ID=BOL:70886887

BOLNumber=70886887

PRONumber=

DeltaFreight=119.43

Freight=119.43

CODAmount=0.00


Declared Value=0.00

Weight=250.00

Service=LTL

SCAC=HMES

Carrier=Holland


Order Number=2067


PO Number=09-32

Department=

Freight Billing=S



DocumentType=Order

DocumentKey=2068

CarrierType=0



Service Code=LTL



Shipment ID=16

ReturnShipment=N

User ID=admin






User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Shipment Field 1=

Shipment Field 2=

Shipment Field 3=

Shipment Field 4=

Shipment Field 5=

Order Field 1=

Order Field 2=

Order Field 3=

Order Field 4=

Order Field 5=

InternalID=16

SHIP VIA=TRUCK


[ITEM_002_001]


UOM=EA

Extra Key1=

Extra Key2=


Extra Key3=


DeltaShipQty=3

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_002_002]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_002_003]


UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[PACKAGE_001]

Zone=

Package ID=-1

Package Number=1

Package Quantity=1


Freight Class=55

Length=0

Height=0

Width=0






Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=1


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000656

Package Type=Box

[CONTENT_001_001]








[CONTENT_001_002]








[PACKAGE_002]

Zone=

Package ID=-1


Package Number=2

Package Quantity=1


Freight Class=65

Length=0

Height=0

Width=0





Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=1


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000663

Package Type=Box

[CONTENT_002_001]








[CONTENT_002_002]









[CONTENT_002_003]








[PALLET_001]

Handling Unit ID=1














Zone=

SSCC=004000081000000625

License Plate=







Pallet Field 1=

Pallet Field 2=

Pallet Field 3=

Pallet Field 4=

Pallet Field 5=

[SETTINGS]

UpdateFreightFlag=Y


8.7 Sample Customer – INI

Sample Document:

[Document]

DocumentKey=AAACO


DocumentType=Customer

Cust No.=AAACO

Ship To Name=AAA Company

Terms=NET10

Ship To Address Line 1=10501 San Pedro Avenue


Ship To Address Line 2=

Ship To City=San Antonio

Ship To Contact Name=SHIP2 Addr Contact

Ship To Phone=80055512557800

Ship Via=ROADWAY

Ship To State=TX

Ship To Zip=78249

Company Name=My Test Company

Company Contact person=James Cray

Company Address 1=1234 West Oak Parkway

Company Address 2=

Company City=Chicago

Company State=IL

Company Zip code=60601-4277

Company Phone=3125552671


[SHIPMENT_001]

OrdNum=AAACO

Status=Add

Shipment Number=1

ID=1Z1235550300007139

TrackingNumber=1Z1235550300007139

BOLNumber=

PRONumber=

DeltaFreight=7.79

Freight=7.79

CODAmount=0.00


Declared Value=0.00

Weight=5.00

Service=UPS Ground

SCAC=UPS


Order Number=AAACO

Customer Number=AAACO

PO Number=

Department=

Freight Billing=S

Freight Account=123555




















Notes=Shipped on 8/5/2011 from Default<cr>End Shipment(s)

DocumentType=Order

DocumentKey=AAACO

CarrierType=UPS

Service Code=03


ReturnShipment=N

User ID=admin






User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

[PACKAGE_001]

Zone=4

Package ID=-1

Package Number=1

Package Quantity=1

Packaging=BOX

Freight Class=NA

Length=0

Height=0

Width=0


Actual Weight=5.00


Package Content=

Tracking Number=1Z1235550300007139

Billed Weight=5.00

Charges=7.79

Freight Billing=S

Freight Account=123555

Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















User Defined 1=

User Defined 2=


User Defined 3=

User Defined 4=

User Defined 5=

[SETTINGS]

UpdateFreightFlag=Y


8.8 Sample Document with Packaging – INI

Sample Document:

[Document]

DocumentKey=62


DocumentType=Shipment

Cust No.=JBT01

Order No.=62

PO Number=

Ship To Name=Joe's Bike Tours

Ship To Contact Name=Joe Smith

Ship To Address Line 1=1 Lost Way

Ship To Address Line 2=

Ship To City=San Francisco

Ship To State=CA

Ship To Zip=45322

Ship To Phone=1234567890

Terms=NET30

[Item1]

Item No.=MBBA01


Item Description=Bike Assy

Ordered Units=1.000


Unit Weight=25.000

Units To Ship=1.000

Item UOM=EA

[Item2]

Item No.=MBBA02


Item Description=Handlebars

Ordered Units=1.000


Unit Weight=5.000

Units To Ship=1.000

Item UOM=EA

[Item3]

Item No.=MBBA03


Item Description=Brakes

Ordered Units=2.000


Unit Weight=2.300

Units To Ship=2.000


Item UOM=EA

[Package_1]

Package Weight=30.000

Package Comment=Bike Frame in here

Handling Unit ID=1

[Content_1_1]

Package Content Item Number=MBBA01

Package Content Item Quantity=1

Package Content Order Number=62

[Package_2]

Package Weight=35

Package Comment=Handlebar and brakes in here

Handling Unit ID=2

[Content_2_1]




[Content_2_2]




[Unit_1]

Handling Unit ID=1

Handling Unit Pallet Type=Pallets

[Unit_2]

Handling Unit ID=2

Handling Unit Pallet Type=Pallets


[SHIPMENT_001]

OrdNum=62

Status=Add

Shipment Number=1

ID=BOL:70887006

BOLNumber=70887006

PRONumber=

DeltaFreight=247.76

Freight=247.76

CODAmount=0.00


Declared Value=0.00

Weight=65.00

Service=LTL

SCAC=NPME

Carrier=New Penn Motor Express


Order Number=62

Customer Number=JBT01

PO Number=

Department=

Freight Billing=S























DocumentKey=62

CarrierType=0



Service Code=LTL



Shipment ID=17

ReturnShipment=N

User ID=admin






User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Shipment Field 1=

Shipment Field 2=

Shipment Field 3=

Shipment Field 4=

Shipment Field 5=

Order Field 1=

Order Field 2=

Order Field 3=

Order Field 4=

Order Field 5=

InternalID=17

SHIP VIA=FEDEX

[ITEM_001_001]

ItemNumber=MBBA01

UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=1

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=


Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_001_002]

ItemNumber=MBBA02

UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=1

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_001_003]

ItemNumber=MBBA03

UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[PACKAGE_001]

Zone=

Package ID=0

Package Number=1

Package Quantity=1


Freight Class=100

Length=0

Height=0

Width=0


Actual Weight=30.00


Package Content=Bike Assy

Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00




















Handling Unit ID=1


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000694

Package Type=Box

DocumentKey=62

[CONTENT_001_001]








[PACKAGE_002]

Zone=

Package ID=1

Package Number=2

Package Quantity=1


Freight Class=300

Length=0

Height=0

Width=0


Actual Weight=35.00


Package Content=Brakes

Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00


Hazardous=N

Handling Fee=0.00



















Handling Unit ID=2


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000700

Package Type=Box

DocumentKey=62

[CONTENT_002_001]








[CONTENT_002_002]








[PALLET_001]

Handling Unit ID=1

Handling Unit Internal ID=1














Zone=

SSCC=004000081000000670

License Plate=


DocumentKey=62






Pallet Field 1=

Pallet Field 2=

Pallet Field 3=

Pallet Field 4=

Pallet Field 5=

[PALLET_002]

Handling Unit ID=2














Zone=

SSCC=004000081000000687

License Plate=


DocumentKey=62






Pallet Field 1=

Pallet Field 2=

Pallet Field 3=

Pallet Field 4=

Pallet Field 5=

[SETTINGS]

UpdateFreightFlag=Y


8.9 Sample Error message Input [ERROR]

Document not found<br>


Please check the document number and re-enter

8.10 Sample Quote Response – XML


<WriteShipment>


DocType="Shipment" DocumentType="Shipment" SourceCompanyName="Sample Retail Company" SourceID="94"


<FreightInfo>

<Shipment>

<Sender ID="MAIN" NAME="V-Technologies" CONTACT="Eric Brown" ADDRESS1="10 McKee Pl"

ADDRESS2="" ADDRESS3="" CITY="Cheshire" STATE="CT" ZIP="06410" COUNTRY="US" PHONE="2031235647"

EMAIL="[email protected]" RESIDENTIAL="False"/>

<Recipient ID="JBT01" NAME="Joe's Bike Tours" CONTACT="Joe Smith" ADDRESS1="1 Lost Way"

ADDRESS2="" ADDRESS3="" CITY="San Francisco" STATE="CA" ZIP="45322" COUNTRY="US"


<BillTo ID="" NAME="" CONTACT="" ADDRESS1="" ADDRESS2="" ADDRESS3="" CITY="" STATE=""

ZIP="" COUNTRY="US" PHONE="" EMAIL="" RESIDENTIAL="False"/>


<NameValue Name="ID" Value="BOL:" ValueType="Shipment"/>

<NameValue Name="BOLNumber" Value="" ValueType="Shipment"/>


<NameValue Name="MasterTrackingID" Value="" ValueType="Shipment"/>

<NameValue Name="Status" Value="QUOTE" ValueType="Shipment"/>










<NameValue Name="SCAC" Value="NPME" ValueType="Shipment"/>

<NameValue Name="Carrier" Value="New Penn Motor Express" ValueType="Shipment"/>





<NameValue Name="Customer Number" Value="JBT01" ValueType="Shipment"/>

<NameValue Name="PO Number" Value="" ValueType="Shipment"/>





























<NameValue Name="DocumentKey" Value="62" ValueType="Shipment"/>



















<NameValue Name="SHIP VIA" Value="FEDEX" ValueType="Source"/>

</Shipment>

</FreightInfo>

End Shipment(s)"


<OrderItems>

<OrderItem>


















</OrderItem>

<OrderItem>



















</OrderItem>

<OrderItem>


















</OrderItem>

</OrderItems>

</SourceDocument>

<BatchName/>

<Settings/>

<Packaging>

<Package>















<Row Name="Package Content" Value="Bike Assy" ValueType="Shipment"/>









































</HandlingUnit>

<HandlingUnit>






























</HandlingUnit>

</HandlingUnits>


</WriteShipment>

8.11 Sample Quote Response – INI [SHIPMENT_001]

OrdNum=62

Status=QUOTE

Shipment Number=1

ID=BOL:

BOLNumber=

PRONumber=

DeltaFreight=778.87

Freight=778.87

CODAmount=0.00


Declared Value=0.00

Weight=600.00

Service=LTL

SCAC=NPME

Carrier=New Penn Motor Express


Order Number=62

Customer Number=JBT01

PO Number=

Department=

Freight Billing=S




















Notes=Shipped on 12/30/1899<cr>End Shipment(s)


DocumentKey=62

CarrierType=0

MasterTrackingID=


Service Code=LTL



Shipment ID=0

ReturnShipment=N

User ID=admin







User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Shipment Field 1=

Shipment Field 2=

Shipment Field 3=

Shipment Field 4=

Shipment Field 5=

Order Field 1=

Order Field 2=

Order Field 3=

Order Field 4=

Order Field 5=

InternalID=0

SHIP VIA=FEDEX


[ITEM_001_001]

ItemNumber=MBBA01

UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=1

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_001_002]

ItemNumber=MBBA02

UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=


DeltaShipQty=1

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[ITEM_001_003]

ItemNumber=MBBA03

UOM=EA

Extra Key1=

Extra Key2=

Extra Key3=



DeltaShipQty=2

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Item Field 1=

Item Field 2=

Item Field 3=

Item Field 4=

Item Field 5=

[PACKAGE_001]

Zone=

Package ID=0

Package Number=1

Package Quantity=1


Freight Class=100

Length=0

Height=0

Width=0


Actual Weight=30.00


Package Content=Bike Assy

Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=1


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=

User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=


Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000830

Package Type=Box

DocumentKey=62

PACKTESTVALUE1=004000081000000830

[CONTENT_001_001]








[PACKAGE_002]

Zone=

Package ID=1

Package Number=2

Package Quantity=1


Freight Class=300

Length=0

Height=0

Width=0


Actual Weight=35.00


Package Content=Brakes

Freight Billing=S


Declared Value=0.00

COD Type=None

COD Amount=0.00

Hazardous=N

Handling Fee=0.00



















Handling Unit ID=2


Weight UOM=lbs

License Plate=

Package Comment=

User Defined 1=

User Defined 2=


User Defined 3=

User Defined 4=

User Defined 5=

Pack Field 1=

Pack Field 2=

Pack Field 3=

Pack Field 4=

Pack Field 5=

SSCC=004000081000000847

Package Type=Box

DocumentKey=62

PACKTESTVALUE1=004000081000000847

[CONTENT_002_001]








[CONTENT_002_002]








[PALLET_001]

Handling Unit ID=1














Zone=

SSCC=004000081000000816

License Plate=


DocumentKey=62






Pallet Field 1=

Pallet Field 2=

Pallet Field 3=

Pallet Field 4=

Pallet Field 5=

[PALLET_002]

Handling Unit ID=2















Zone=

SSCC=004000081000000823

License Plate=


DocumentKey=62






Pallet Field 1=

Pallet Field 2=

Pallet Field 3=

Pallet Field 4=

Pallet Field 5=

[SETTINGS]

Document History

Updated on Updated By Description

7/11/2008 J. Volta Create Document

8/8/2008 F. Oatess Updated to correct default configuration file location, add delete status to Shipment file, add brief explanation of sequential process and file handling in section 6

8/14/2008 F. Oatess Added note on length of interface name, reformatting, updated file samples

8/27/2008 F. Oatess Added section 3.6 “Error Message Files” from integrated application to StarShip, updated File Handling example in section 6

10/7/2008 F. Oatess Corrected default mode and clarified required files

10/17/2008 C. Pillsbury Modified configuration file chart to show Document Name is required, and sample StarShip Shipment File to show breakdown of shipment charges

10/20/2008 F. Oatess Added comment to section 7 – Backwards Compatibility will be available in a future release


12/23/2008 F. Carnevale Added section Error! Reference source not found. – discussion of sample files

6/11/2009 F. Carnevale Updated section 3.6 “Error Message Files” to include XML format

3/2/2010 J. Volta Section 2 – Used default configuration file path for paths in sample configuration files.

Section 3.4 - Updated field value list format to match actual.

Removed section 7.2 – using StarShip 9.x and 10.x concurrently. Section 7.3 now 7.2

03/23/2010 E. Brown Replaced “Ship” with “Add” as the write back status

04/13/2010 E. Brown Section 2. Configuration File – Input File Name Mask – added note that StarShip 9.x compatible station number is a backwards compatible feature that has not been implemented yet.

Header\Document – Corrected labels for some fields in table.

Company – Corrected labels for some fields in table.

Section 3.2 Document File – SelectResult section of table – added HandlingUnits section.

Section 3.3 StarShip Shipment File table – added HandlingUnits section.

Section 3.4 Field List File – FSIField – Removed incorrect reference to attributes. This field contains no attributes.

FSIFIeld\FSI_InputValues – Removed reference to Company Attribute … not implemented.

04/15/2010 E. Brown Section 2. Configuration File – Input File Name Mask – Removed information that this value was not required.

05/05/2010 E. Brown Added note to Section 3.3.1 Shipment\NameValue row and Section 3.3.2 Shipment# and Package# rows that these name value pairs are still in development.

Section 3.3.2 - Change header for package to be ”Package###” instead of “PKG###”.

Section 7.2 - Added that there will be a setting that causes StarShip to create the shipment file in the 9.x ADE format.

04/07/2011 E. Brown Added note to Section 3.3.1 Package\NameValue

11/20/2012 E. Brown Section 3.2 Added note about XML Code Page to XML Example Note.

Section 2.0 Added DateTimeStamp variable to “StarShip Request File Name”

Section 3.3.1 and 3.2 Added note to for Package ID

07/23/2013 E. Brown Section 3.3 added new Shipment and package fields.


12/04/2013 E. Brown Sections 3.3.1 and 3.3.2 Corrected description of CarrierType and Carrier fields for write back section.

12/18/2013 E. Brown Updated address, moved change log.

02/21/2014 E. Brown Added descriptions for new fields in the shipment file. Clarified description of Package ID and Handling Unit ID fields and added Handling Unit Internal ID field.

06/08/2015 E. Brown Updated Shipment document notes, correcting description of Package ID.

11/06/2015 E. Brown Added Section 5.3 Custom Write-Back. Updated 3.4 Field List File with new fields for supporting Custom Write-Back. Updated

HasValueList (manual lists) and FSI_InputValues. Updated Section 5.2 where related to Custom Write-Back. Updated Shipment file with info relevant to Custom Write-Back. Added note to Section 3.5 Default Map file.

11/23/2015 E. Brown Updated example output files. Updated User Defined Field description.

StarShip Developer Interface - Shipping Softwaredocs.vtechnologies.com/SS_Dev_Interface.pdf ·...

Documents

Transcript of StarShip Developer Interface - Shipping Softwaredocs.vtechnologies.com/SS_Dev_Interface.pdf ·...