KB: Item Import Guide (Classic + Portal)

1. Overview & Purpose

Item Import lets you create and update item master data in bulk from a CSV file, instead of keying items in one by one.

The function exists in two places — Classic and Portal — and both use the same CSV format. A file generated in Classic can be uploaded in Portal, and vice versa. Which one you use is a matter of convenience, not compatibility.

Key benefits:

• Bulk-create new items, or bulk-update existing ones, in a single upload
• One file format to learn, shared across both Classic and Portal
• The CSV is customisable — you can delete columns you do not want to touch, so an import updates only the fields you actually care about (see Section 4)
• Both systems report per-row results with a reason for every failure — Classic via a result file, Portal via an on-screen preview

2. Where the Import Function Lives

2.1 Classic — System Configuration → Import

1. Open System Configuration
2. In the left-hand settings list, select Import
3. The Import Settings page opens. Scroll to the Item section

Under Item you will find two rows, each with its own pair of buttons:

Other import rows on the same page (Barcode, Bill of Material, Client, Item Image, Product Matrix, Vendor) follow the same Import / Generate File Format pattern but take their own file formats — do not mix them with the item file.

Generate File Format is the canonical source of the template. Always regenerate a fresh template from the version of Xilnex you are importing into, rather than reusing an old file you have lying around — the column set is version-dependent and can gain columns between releases.

The page header shows the profile scope (e.g. All Outlets). Confirm you are on the intended scope before importing.

2.2 Portal — Product Information Management → Item Import and Log

1. In Portal, go to Product information management
2. Open Item import and log
3. The Item Import And Log screen opens, showing the history of previous imports
4. Click the green IMPORT button at the top-right to upload a file (the REFRESH button beside it reloads the list)
   

The log table below lists every import that has been run:

This log is your verification step. After every Portal import, check that Success = Total and Failed = 0. A row showing Total 21 / Success 0 / Failed 21 means the whole file was rejected — that is almost always a format or column problem, not 21 separate data problems.

The table is paginated (10 / 25 / 50 / 100 per page) with total record counts at the bottom, so past imports remain available for audit.

3. The CSV File Format

Both systems consume the same CSV. Generate it from Classic via Generate File Format, fill it in, and upload it to whichever system you prefer.

Structure of a generated file

Line 1:  @@##Write Time:06082026 095106
Line 2:  Item Code,Item Name,Alternate Lookup,Attribute,Brand,Category,...
Line 3+: <your data rows>

• Line 1 is a generator stamp written by Generate File Format — leave it as generated
• Line 2 is the header row — this is the row that defines which fields the import will write
• Line 3 onwards are your data rows, one item per row

The full generated template contains roughly 150 columns covering the entire item master. You are not expected to fill all of them — see the next section.

4. Customising the CSV — Updating Only the Columns You Need

You do not have to keep every column. The header row is what drives the import: whatever columns you leave in the file are the fields the import will write. Columns you delete are simply not part of that import, so their existing values in the system are left alone.

This is what makes the import useful for fixing a missed update. If a batch of items went in with the wrong selling price, you do not need to rebuild the full item file and risk overwriting other fields — you cut the file down to just the price column and re-import.

Whichever columns you delete, keep the identifying column — Item Code. Partial update works by matching your rows against existing items on that code, so it has to stay in every file.

Worked example — a price-only correction

Full template header (abridged):

Item Code,Item Name,Alternate Lookup,Attribute,Brand,Category,...,Price 1,Price 2,...

Cut down to a price-only correction file:

@@##Write Time:06082026 095106
Item Code,Price 1
ITEM001,15.90
ITEM002,22.50
ITEM003,8.00

Result: Price 1 is updated on those three items. Names, categories, tax codes, flags and everything else are untouched.

Other common cut-down files

Rule of thumb: if a column is in the file, treat its value as authoritative — a blank cell in an included column is still a value being sent. If you do not intend to change a field, remove the column rather than leaving it empty.

5. How to Import — Classic

1. System Configuration → Import → Item
2. Click Generate File Format on the Import items data row to download a fresh template
3. Open the template in Excel or a text editor and fill in your data rows
4. Delete any columns you do not want this import to touch — keep Item Code
5. Save as CSV (not .xlsx)
6. Back on the Import Settings page, click Import on the Import items data row
7. Select your file and let it process
8. Open the result file in the \Webbytes\ImportStatus folder and check the Status column on every row (see Section 7.1)
9. Verify the affected items in the item list / Item Management before doing anything downstream

For supplementary fields, repeat the same process using the Import item additional info data row and its generated template — it is a separate file, not extra columns on the main one.

6. How to Import — Portal

1. Product information management → Item import and log
2. Click the green IMPORT button (top-right)
3. Select your CSV file
4. Click REFRESH to reload the list if your import does not appear immediately
5. Find your file in the log table and check the counts:
   • Success record(s) should equal Total record(s)
   • Failed record(s) should be 0
6. To see per-row results, click the … button on that log row and choose Preview — this is the only way to read why individual rows failed (see Section 7.2)

Re-importing a corrected file is safe for partial updates — the same rows are matched on Item Code and rewritten. Each attempt is logged as its own line, so the log shows the full history of a fix (see the two ItemTemplate (14).csv entries in the sample log — one at 2/4 success, then a clean 4/4 run).

7. Import Results & Error Reporting

Every import produces a per-row result, in both systems. Do not judge an import by whether it "ran" — always read the result. Rows can fail individually while the rest of the file imports fine.

The two systems expose the same information in different places.

7.1 Classic — the \Webbytes\ImportStatus folder

After a Classic import, a result file is written to the \Webbytes\ImportStatus folder. It is a copy of the imported CSV with a Status column added as the first column, so every row carries its own outcome.

Filename pattern: Item<ddMMyyyy><HHmmss>.csv — e.g. Item21112023102033.csv for an import run on 21 Nov 2023 at 10:20:33.

Structure:

@@##Write Time:21112023 102033
Status,Item Code,Item Name,Alternate Lookup,...
Import completed.,RECIPE001,recipe 001,,,...
Failed as cannot update item type for existing item.,RECIPE001,recipe 001,,,...

Fixing and re-importing: the result file is your worklist. Filter to the failed rows, correct them, delete the Status column, and re-import that cut-down file. The successful rows are already applied and do not need to be re-sent.

7.2 Portal — the result preview

In the Item Import And Log table, click the … button on an import row, then choose Preview. This opens the Preview file — <filename>.csv dialog, which shows the same per-row outcome on screen:

The dialog is paginated (10 / 25 / 50 / 100) and has two buttons at the bottom:

• DOWNLOAD — saves the result file, for working through failures offline or keeping as an audit record
• DISMISS — closes the dialog

Example from a real run:

Note the ordering problem this exposes: ET-postpack11 referenced ET-prepack11 as a sub-item, and ET-prepack11 referenced ET-normal — but ET-normal was further down the same file and did not exist yet when those rows were processed. Import component items before the packages that reference them, either by ordering rows correctly or by splitting into two imports.

8. Column Reference (Grouped)

The template's ~150 columns fall into these groups. The authoritative list for your version is always the file produced by Generate File Format — use this table to orient yourself, not as a substitute.

9. Best Practices

• Always regenerate the template from Generate File Format rather than reusing an old file — column sets change between versions
• Test small first — run 2–3 rows before a 500-row file, and confirm the result before scaling up
• Cut the file down to what you are changing. Fewer columns means fewer ways to accidentally overwrite good data
• Open CSVs in a text editor to verify before uploading, especially dates (dd/MM/yyyy) and any code Excel likes to mangle into scientific notation or strip leading zeros from
• Make sure master data exists first — categories, departments, vendors, UOMs and tax codes referenced in the file should already be set up
• Use Portal when you want an audit trail — the import log records every attempt with counts
• Check outlet scope — in Classic, confirm the scope shown on the Import Settings page; use the Outlet column (with | between multiple outlets) where item-to-outlet assignment matters

10. Troubleshooting

Start every investigation with the per-row result — \Webbytes\ImportStatus in Classic, … → Preview in Portal (Section 7). The reason is written on the row itself; the table below maps the common ones.

11. To Confirm

Not verified at time of writing — to be filled in from testing or product knowledge:

• Whether the @@##Write Time: line on line 1 is required by the parser, or whether a file without it still imports
• The full path / drive root of the \Webbytes\ImportStatus folder, and whether it is local to the machine that ran the import or on a shared server location
• Whether Classic and Portal validate identically, or whether one is stricter than the other
• Whether an unknown Item Code creates a new item or is rejected (i.e. is the import upsert or update-only?)
• Whether Portal writes a result file to disk as well, or only exposes it via Preview → DOWNLOAD

---

FAQ