Advanced

Advanced Stuff, Corner Cases, Exceptions and Entity-Specific Advice

Stamping

Stamping is a somewhat advanced concept, but important if you intend to import particularly complex transactions like Purchase Orders and Sales Orders.

Stamping is where data from one entity record is 'stamped' into the transaction you are creating. Stamping is done in many places automatically by the admin panel. For example, when you create an order and choose a customer, multiple fields from the Customer record are 'stamped' into the order - like their name, email address and even payment terms.

You need to know that 'stamping' is not done automatically in CSV imports. In other words you need to import the field that 'connects' the Order to the Customer (the primary identifier of the customer) as well as all the above mentioned fields that would normally be stamped by admin panel. As always, the easiest way to get to grips with this is to do an export first, examine the fields that are there, test some imports and see what is missing, then add those fields.

Calculated Fields

Similar to 'stamped' fields, but technically very different, are server-calculated fields, like line or transaction totals. These are fields that are automatically calculated by the server when you save a transaction. These fields are calculated when doing an import (in contrast to stamped fields). You can't import them, and even if you could they'd be overwritten when the transaction was saved. The most common examples of calculated fields are:

• Line totals on transaction lines

• Transaction totals

• Customer and supplier balance fields

• Stock levels

Validations

Some of the failure messages you might see when running imports are not simple 'required field missing' errors, but more complex 'validations'. Validations are checks that are run by the server when you an attempt to import - they are guarding against bad data and impossible situations. When taken out of context however, they can be a bit cryptic. For example, if you are editing a Sales Order via CSV Import and you end up seeing a message about 'Dispatching more items than are committed' or something similar - you might not realise that the reason is because the edit you are making is essentially 'invalid'. The validations you might see after a CSV import are the exact same error messages you are liable to see in the admin panel if you tried to make the same edit.

Importing Sales Orders

Given that importing orders to the system from external sources is by far the most common import requirement, we feel the subject deserves special attention. Here are some pointers:

• Remember to import all the customer 'stamped fields': name, email, billing email, payment terms etc

• Due to a technical difference the payment method and shipping method on Orders need to be set in a specific way. Use the column headers shippingMethod._id and paymentMethod._id with the internal ID (the ones that looks like 5f75a30ada066b516dfaa96d). Shipping and payment surcharges will be auto-calculated for new records, but not for edits

• On Order lines, set the product sky, name, weight, price, tax code and percentage, but don't set any of the line calculations - those will be done automatically

• Definitely don't try to set the order totals