Customize Interface


In this topic

Customize Interface Window

Field Mapping

Minimum Fields Required

Sender Values

Recipient Address ID Notes

Map the Ready Date/Time

Value Translations



StarShip allows you to customize the way data is translated between your source interface documents (orders, customers, etc.) and the StarShip Ship screen. Customize Interface controls how the data in the source document is translated. It defines what information populates the shipment fields, and how the data is interpreted into accepted shipment values. A set of field maps and value translations is called an "interface".

StarShip comes with one predefined interface called "My Interface" that installs default field maps for your source interface documents, which you can customize. You can also create multiple interfaces to use with different companies if you plan to map to user-defined fields that vary between companies.  

In summary, the interface defines:

You will either access an interface from Setup > Source Interface > Customize Interface, or from the Initial Setup wizard. Then, you must select an interface and a document type (Orders, Invoices, Customers) to access the Customize Interface window, where you can define field mapping and field values.




Customize Interface Window

This is an example of what you might see on the Customize Interface window. The next section explains each portion of this window.



1. Target Fields (Left-Most Section)

Fields from the StarShip shipment entry screen are organized into topics or "groups": Recipient, Sender, Order, Shipment, and Rate Shop. To expand a group, click the " + " next to it. Click the group itself to display its fields in the center pane.

2. Shipment Fields (Middle Section)

This section shows the subgroups and fields for the currently selected Target Field group on the left. Click on an item to display its description and its existing field mapping configuration to the right. In the example above, you can see that Carrier - Service is the selected shipment field and its current mapped value shown in the field mapping source (4) to the right.


3. Description (Right-Most Section)

This is a description of where you can find the currently selected shipment fields.


4. Field Mapping Source

Shows the map settings (the source value) for the currently selected shipment field. These are your choices:

5. Order, Customer, or Invoice Field

Select a field from the source document as the mapped source for the selected StarShip shipment field. A short description of where you can find the field in the source interface may be available.  

This field will not appear if Source is set to None or Fixed Value. Click the magnifying glass icon for a searchable list of fields from the source interface.


Field Mapping

Many fields in the source interface are mapped by default as part of the basic interface. If you want more control over how data is translated from your source interface into shipment fields, you can add or customize field mapping to suit your company's needs. See Minimum Required Fields for a list of fields that StarShip needs to process shipments.

For example, a common field map is from "Ship Via" in the source interface to "Carrier" in StarShip. It's a default field map but you can customize it based on the carrier values set up in your source interface. Here's how to do that:


  1. Click Customize Interface.

  2. Select the document (Orders, Customers, etc.).

  3. Expand the Target Field group "Shipment."


  4. Select Carrier Information.


  5. In the Shipment fields section, choose Carrier. Note that the Field Mapping Source is set to "Source Interface" Field and the source document field (Order field, Customer field, etc.) is set to Ship Via.


  6. Select "Click here to update Value Translations."


  7. The Value Translations dialog shows you the way Ship Via is currently mapped to the Carrier field in StarShip. This is where you can adjust the values by making selections from the drop-down lists:

Minimum Fields Required

For users of SQL Interfaces, Developer Interfaces, or any users who plan to unmap key fields : The following minimum fields are required for StarShip to retrieve enough information to process a shipment.



Company, Address 1, City, State, Postal Code, Country




All fields above, plus Order number, Carrier + Service (Ship Via)




All fields under Customers, plus Item Number, Item Description, Ordered Units




All fields under Customers, plus Packaging




The following minimum fields are required for StarShip to retrieve enough information to perform write-back to the source interface.



To Write-Back

Minimum Field Required

Freight $

a numeric field (ex. an SQL type “money” field)


an unlimited length text / string field (ex. an SQL type “varchar (MAX)” field)

Tracking #

a text / string field at least 25 characters long (ex. an SQL type “varchar (25)” field)



Sender Values

When you ship against source interface documents (Orders, Invoices, etc.), you can have the Sender information automatically populated on the shipment by either mapping fields to the source ERP or by defaulting the Sender values. The StarShip fields will populate differently depending upon the fields that are mapped. Basically, if no Sender fields are mapped, the Sender information will be populated with the default Company information.



Sender Address ID

If the Sender Address ID is mapped and matches a Sender Address ID in the StarShip database, StarShip will ignore all other Sender Address field data that is imported via field mapping. The fields are populated from the StarShip database.

If the Sender Address ID is not mapped, or is mapped and does not match a Sender Address ID in the StarShip database, the Address ID on the Sender tab will not be populated. In this case, if the Sender Address fields are mapped, the source interface Sender Address is used. If Sender Address fields are not mapped, the address fields on the Sender tab will default to the Sender address in StarShip.



Sender Account

If the Sender Account is mapped to the source interface and the account number that is imported does not match the account number associated with the Sender Address ID, the address will not be populated at all. To map a non-matching Sender Account without blanking out the address, you can either





Recipient Address ID Notes

When importing a document from your source interface, even if the Customer ID and/or Address ID fields are mapped, recipient fields are populated with data from the source interface. It will not be populated from StarShip Customer data.



Map the Ready Date/Time

The following notes refer to the Ready Date/Time on the Shipment tab.


Ready Date

Ready After Time / Ready Before Time (Freight Mode)

These fields can be mapped using the ##AM and ##PM format to set a window for the pickup time. If the Ready Date is also mapped, the Shipment tab displays the pickup time window for that date. If the Ready Date is not mapped, the pickup time window will be set for the current day. If the current time is already past the time mapped to Ready After Time, the Pickup From time is set to the current hour.








Value Translations

This section provides more details about what value translations are and how they work.


There are two types of shipment fields:

In the latter case, once these shipment fields are mapped to your source interface fields, we then need a way to make sure that StarShip gets values that it recognizes. We need to define value translations for those fields. So, value translations define how the values from your source interface are translated into shipment fields that require a set of allowed values. Values are set up in your source interface; one example is Billing Type values.




Value Translations dialog

This dialog is accessible when you have mapped a StarShip shipment field to a field in the source interface and you select the "Click here to update value translations" link.







1. Refresh Values or Edit Values

Refresh Values: Press Refresh Values, or Alt + R, if you have made changes to the values in the source interface.

Edit Values: If you are mapping to a shipment field in StarShip that accepts a list of values, but there is no value list in the source interface, the Edit Values button will appear. The Edit Values function allows you to type in a list of possible field values.

To add values for a field, click the Edit Values button, or Alt + E. Type a value into the field and press Add. Repeat this process for all values you want to add. Click OK when you are done.





2. Set all translations to

Use the "Set all translations to:" field to change all value translations for the source interface field to one shipment field value.



3. Source Interface field value

This is the list of values for the source interface field.



4. Shipment field value

This is the list of StarShip shipment values.



5. Other fields that are mapped to the source interface field

Any other fields that are mapped to this source interface field will display here. You can click on the field to work with its value translations.




6. Value translation for the currently selected row

The value shown here reflects the row selected in the top pane. To change the value, click it and make a selection from the drop-down list.




Default Value Translation Rules for Ship Via /Ship Method Source Interface Fields

To obtain the matching carrier from the source interface when a carrier exists in the StarShip database, the following rules are applied in this order:

  1. If an identical carrier exists, then it is selected...

  2. ...otherwise the carrier whose SCAC matches exactly gets selected.

  3. If not found, then StarShip selects the carrier with a similar name.

  4. If no similar match is found, StarShip does not select a carrier. The value translation defaults to the first carrier available in the list.