Import

The CSV import framework obviously observes the above conventions, but there's a little bit more you need to know.

Start with an export. As I said earlier - there's no need to download a data template or example file, and you shouldn't guess at field names from the labels you see in the admin panel. Just go to the entity you are looking to import, hit the export button, and use that as your template. If you just want a starting point with only required fields, choose the 'Only Required Fields' option on the export dialogue, but bare in mind this won't give you all the fields for lines (if you are importing a transaction).
Column order is not important. Only the column name is important to getting the import right, not the order.
You must include the exportLineType field for every line in your import. Remember, for top-level records it will be MAIN; for other types of lines, you'll need to include the correct line type (which you can reference from an export).
Include the ID to update. Omit the ID to create new. CSV import can be used for creating new records as well as bulk editing existing records. If you include the internal_id field (which, technically, is a MongoDB unique identifier, if you must know, but more importantly is always the first field in an export), that record will be an update/edit. If you omit the _id field, that line will be a new record creation.
Include an exportLineNumberPath to edit an existing line, omit to create a new line. Remember that lines 'belong' to the MAIN line above it - so if you want to edit transaction lines, you need to include the MAIN line for that transaction, even if you don't need to make any edits to the actual transaction. So, if you want to edit Order Line 5 of an existing order, you will need a MAIN line for the actual order, then another import line with exportLineNumberPath set to 5 with the actual line edits.
You can mix new creation and updates in a single import. Leaving the _id column in, but only including IDs for some lines will result in a mixed import where some lines will cause new records to be created, and others will cause updates to existing records. Likewise you can mix line edits and new line creations.
Updates are "patches" not complete overwrites. That means that when updating records, only the fields present in your import will be applied to the existing record - it won't overwrite the whole thing.
Not all columns need to be present. Disregarding required fields on new record creation for a moment, you don't need to include all the columns in your imports. If you are using a CSV import for a bulk update, you can keep your sheet clean and only include the columns you need to update. Again, only those fields will be updated - everything else will be left alone.
Blank fields are not updated. One way of excluding a field from being updated is just not including the column at all (see above), but another option is to just leave it blank.
Deletion is explicit. It follows from the above that if you want to explicitly delete a field, leaving it blank won't work. For that we have a special tag: <DEL>. Setting the field value to that tag, written exactly in that way, will delete the field contents. What if you want to actually set a customer's name to <DEL>? Sorry, you can't!
Respect required fields. There are less required fields in Pakk than other systems because the system uses 'sane' defaults (see below), but some fields really are required, and their field label is marked with a *. Without those fields, that import line will fail.
Sane Defaults. For new record creation, you can optionally omit quite a lot of fields (see 'Not all columns need to be present') and the system will fill them in with somewhat sane default values: 'blank' for text fields, 0 for number fields, FALSE for checkbox fields, 'empty' for lists, and so on.

If you get a Line type (field name 'exportLineType') is required error and you are 100% sure have a line type for every line of your CSV file, the problem is almost certainly that you have 'phantom' empty lines at the bottom of your CSV file. This is very common when editing in Excel and deleting rows. Open your CSV file in a text editor and look for rows of commas at the bottom of the file. If you see any, delete them right up until the very end of the last data row (even delete the final carriage return/newline).

PreviousList Fields NextReferencing Other Records

Last updated 8 months ago

Import

The CSV import framework obviously observes the above conventions, but there's a little bit more you need to know.

Start with an export. As I said earlier - there's no need to download a data template or example file, and you shouldn't guess at field names from the labels you see in the admin panel. Just go to the entity you are looking to import, hit the export button, and use that as your template. If you just want a starting point with only required fields, choose the 'Only Required Fields' option on the export dialogue, but bare in mind this won't give you all the fields for lines (if you are importing a transaction).
Column order is not important. Only the column name is important to getting the import right, not the order.
You must include the exportLineType field for every line in your import. Remember, for top-level records it will be MAIN; for other types of lines, you'll need to include the correct line type (which you can reference from an export).
Include the ID to update. Omit the ID to create new. CSV import can be used for creating new records as well as bulk editing existing records. If you include the internal_id field (which, technically, is a MongoDB unique identifier, if you must know, but more importantly is always the first field in an export), that record will be an update/edit. If you omit the _id field, that line will be a new record creation.
Include an exportLineNumberPath to edit an existing line, omit to create a new line. Remember that lines 'belong' to the MAIN line above it - so if you want to edit transaction lines, you need to include the MAIN line for that transaction, even if you don't need to make any edits to the actual transaction. So, if you want to edit Order Line 5 of an existing order, you will need a MAIN line for the actual order, then another import line with exportLineNumberPath set to 5 with the actual line edits.
You can mix new creation and updates in a single import. Leaving the _id column in, but only including IDs for some lines will result in a mixed import where some lines will cause new records to be created, and others will cause updates to existing records. Likewise you can mix line edits and new line creations.
Updates are "patches" not complete overwrites. That means that when updating records, only the fields present in your import will be applied to the existing record - it won't overwrite the whole thing.
Not all columns need to be present. Disregarding required fields on new record creation for a moment, you don't need to include all the columns in your imports. If you are using a CSV import for a bulk update, you can keep your sheet clean and only include the columns you need to update. Again, only those fields will be updated - everything else will be left alone.
Blank fields are not updated. One way of excluding a field from being updated is just not including the column at all (see above), but another option is to just leave it blank.
Deletion is explicit. It follows from the above that if you want to explicitly delete a field, leaving it blank won't work. For that we have a special tag: <DEL>. Setting the field value to that tag, written exactly in that way, will delete the field contents. What if you want to actually set a customer's name to <DEL>? Sorry, you can't!
Respect required fields. There are less required fields in Pakk than other systems because the system uses 'sane' defaults (see below), but some fields really are required, and their field label is marked with a *. Without those fields, that import line will fail.
Sane Defaults. For new record creation, you can optionally omit quite a lot of fields (see 'Not all columns need to be present') and the system will fill them in with somewhat sane default values: 'blank' for text fields, 0 for number fields, FALSE for checkbox fields, 'empty' for lists, and so on.

If you get a Line type (field name 'exportLineType') is required error and you are 100% sure have a line type for every line of your CSV file, the problem is almost certainly that you have 'phantom' empty lines at the bottom of your CSV file. This is very common when editing in Excel and deleting rows. Open your CSV file in a text editor and look for rows of commas at the bottom of the file. If you see any, delete them right up until the very end of the last data row (even delete the final carriage return/newline).

PreviousList Fields NextReferencing Other Records

Last updated 8 months ago