Loading a catalogue without loading a mess — transcript

Play this as a presentation — one slide per step, with the same narration. Every word of every step is on this page.

This lesson is for whoever is about to load GadgetSphere’s five thousand items, or a supplier’s new range, from a spreadsheet. The file import is the only sane way to do it and it has four behaviours that nothing on the screen mentions. In about fourteen minutes you will know all four and have a routine that keeps them from costing you a weekend.

Step 1 — Understand that the import is an edit, not just a load

After this step you will never re-upload a file casually again. Every row in a Doc Item file is matched on item code against everything in your catalogue that is not deleted. If it finds a match it updates that item; if it does not, it creates one. There is no create-only mode, and there is no message telling you that eight hundred of your thousand codes already exist. A file you upload expecting it to be rejected as duplicates is instead applied as an edit to every item in it. That includes the item type and tracking-mode columns, which the edit screen locks and this path writes without comment. Before any upload, ask yourself which of these codes already exist, because those rows are edits.

Reference: Doc Item Maintenance — Import is an upsert, not a create

Step 2 — Treat a failed upload as partly applied

After this step you will read a red status correctly. The Doc Item template validates every row, marks the bad ones, and then works through the file one row at a time. A bad row is recorded and skipped; the good rows around it are created and updated exactly as if nothing were wrong. Only at the very end does the upload’s status become failed. Nothing anywhere distinguishes an upload that failed and did nothing from one that failed after writing three hundred of your four hundred items. This is not an edge case: across the ninety tenants, twenty-nine have used this import, and about a third of their uploads ended failed. Every one of those left whatever was valid already committed.

Reference: Doc Item Maintenance — A failed Doc Item import is not a no-op

Step 3 — Know that the template next to it behaves the opposite way

After this step you will stop generalising from one upload to another. The Doc Item With Category template, on the same screen, in the same menu, checks the entire staged file before it writes anything and abandons the run if a single row is invalid. Nothing is created. That is the behaviour most people assume they have, and it is the behaviour you get from one template and not from its neighbour. So a colleague who tells you a failed import is harmless may be perfectly right about the template they used and perfectly wrong about yours. Always name the template when you talk about an upload.

Reference: Doc Item Maintenance — A failed Doc Item import is not a no-op

Step 4 — Expect the rest of the platform not to hear about it

After this step you will know why a bulk change did not reach the storefront. Saving an item on the screen does three things besides writing the row: it raises a catalogue event for anything subscribed to your products, it queues a free-shipping job if that flag changed, and it pushes the item’s status across to its inventory record in the background. The import path calls the version of the same update that does none of them. So a batch of items set inactive by file can leave their inventory records active and still appearing on stock reports and in stocktake, and anything downstream listening for catalogue changes hears nothing at all. The import does create an inventory record for a new basic item, and if that fails it is written to a log rather than shown to you.

Reference: Doc Item Maintenance — Import is an upsert, not a create

Step 5 — Watch the round trip, not just the upload

After this step you will design the file rather than accept it. The export side has its own shape: you can filter which items come out, but not which columns, so an export you intend to edit and re-import comes back wider than you wanted. Every one of those extra columns is a value you are about to write back, and one of them may be a value somebody changed on the screen in the meantime. Two habits fix it. Cut every column you are not deliberately changing out of the file before you upload it — especially the item type and tracking columns. And use the column picker the Doc Item template offers on the way in, which lets you send only the fields you mean.

Reference: Doc Item Maintenance — Export Item

Step 6 — Run the small routine that catches all of it

After this step you have something to do rather than something to worry about. Four steps, and they take longer to describe than to perform. First, prove the file with ten rows before you send five thousand, on codes you are happy to see edited. Second, after any upload that reports failure, open its error tab, note the failing line numbers, and treat every other row in the file as applied. Third, spot-check three items that were supposed to change, using the thirty-second test from the applet page: open the item with the listing filter set to all, confirm the inventory code, the pricing and the classification, and then actually scan it on a draft document. Fourth, for anything you set inactive by file, check one of its inventory records — that is the push the import does not run.

Reference: Doc Item Maintenance — How you know it worked

How the steps fit together

    flowchart TD
  s1["Step 1 — Understand that the import is an edit, not just a load"]
  s2["Step 2 — Treat a failed upload as partly applied"]
  s3["Step 3 — Know that the template next to it behaves the opposite way"]
  s4["Step 4 — Expect the rest of the platform not to hear about it"]
  s5["Step 5 — Watch the round trip, not just the upload"]
  s6["Step 6 — Run the small routine that catches all of it"]
  s1 --> s2
  s2 --> s3
  s3 --> s4
  s4 --> s5
  s5 --> s6
  

Check yourself

Three to five questions on what you just heard. Every correct answer links to the page that makes it correct, so you can check the source, not just the mark.

Back to the series · Play this as a presentation