1 Quick start (60 seconds)

If you only have a minute, here's the whole flow:

1. Drag a product file (image, PDF, or Excel sheet) into the red-bordered Upload Product Files zone — or click it to browse. Folders work too.
2. Wait for AI analysis. A full-screen overlay shows "Analyzing file 1 of N". Each file takes roughly 30–90 seconds.
3. Review the extracted fields. They're organized into 17 collapsible sections. Open any section to see and edit the extracted values.
4. Fix mandatory fields. Empty required fields are highlighted in amber, and each section header carries a small ⚠-with-count pill listing the missing field names on hover. Click it (or jump straight into the section) to land on the first gap.
5. Click Export CIN XML in the header to download the GDSN-compliant XML file.

That's it. The rest of this guide explains each piece in more detail so you know what every button does and why.

2 The page at a glance

The app has three vertical zones:

The page is responsive — below ~900 px the upload and Customer / Project cards stack on top of each other.

3 Header bar

The row at the very top of the page. Left to right:

Start new article (which used to live in the header) now sits in the kebab (⋯) overflow menu next to the Add to Queue button at the top of the editor, so it's close to the queue verbs it pairs with.

4 Uploading files

Three ways to add files

• Drag & drop one or more files onto the upload zone.
• Drag a folder — the app walks the folder tree and picks up every supported file inside.
• Click the upload zone to open the file picker.

Supported file types & limits

• Images (JPG, PNG, GIF, WebP) — up to 100 MB each. Best for product photography and packaging shots.
• PDFs — up to 100 MB. Best for spec sheets, datasheets, supplier briefs.
• Excel (.xlsx, .xls) — up to 20 MB. Best for Markant or supplier data dumps. Excel sheets with hierarchies (pallet → carton → unit) are auto-detected and shown as a tree.
• Text (.txt, .csv, .tsv, .json, .xml) — up to 100 MB.

What happens during analysis

Files are analyzed one at a time, in order. A full-screen overlay shows "Analyzing file i of N". Each file usually takes 30–90 seconds; Excel can take up to 2 minutes.

The overlay has a Cancel button — clicking it stops the remaining files. Already-analyzed files keep their data; only the unprocessed ones are dropped.

Languages filter (DE / FR)

The Uploaded Material toolbar has a Languages: checkbox group with two options — DE (ticked by default) and FR (optional). Every time you click Map data, multilingual values from any other language are dropped before merging. A content-based sniffer also drops mislabelled foreign-script text (Greek, Cyrillic, Czech / Polish / Hungarian / Romanian / Slavic diacritics) even when the AI tags it as de, so a stray "Συστατικά: …" won't sneak into a German-only mapping.

Tick FR before mapping a French-localised product; un-tick DE if you want a French-only mapping. Your selection persists across page reloads.

5 Mapping Defaults Advanced

The card on the right of the top row. It lets you preset key/value defaults that are merged into every extraction — useful when you always work with the same target market, sender GLN, or storage type, for example.

You can save named sets of defaults (Save As, Update, Delete), Download them as a file, or Upload a colleague's defaults file.

6 Editing extracted attributes

Below the top row, you'll see a material grid (thumbnails of the files you uploaded) followed by the attribute accordion — 17 collapsible sections plus a few extras that appear when relevant.

The 17 attribute sections

The sections (in order) are:

1. Identification Article — GTIN, brand, descriptions, classifications
2. Filling Quantities / Weights / Measurements
3. Food — Ingredients / Additives / Allergens / Vitamins
4. Identification Owner / Manufacturer
5. Country of Origin
6. Article Indicators
7. Date Information / Origin
8. Handling — storage temperatures, ambient/chilled/frozen
9. Preparation & Consumer Info
10. Regulatory & Compliance
11. Packaging
12. Battery Information
13. Taxes / Prices / External Trade
14. Hierarchy — pallet dimensions, stacking
15. Marketing
16. Diet, Certifications & GMO
17. Dangerous Goods / Hazardous Substances

After those, depending on your data, you'll also see: Allergens, Nutrition Facts, Nutritional Claims, Contact Information, Additional Attributes, and Extraction Summary.

Section header signals

• Missing-required triangle — when a section has empty mandatory fields, a triangle with the count appears on the right of the header. Hover for the list of field names that still need a value.
• Search match badge — when you type in the search bar, sections show how many matches they contain.
• Compare badges — while compare mode is active (see §7 below), each section also shows how many diff rows still need a Take or Skip decision, plus per-section Take all / Skip all bulk verbs.

Editing a field

Click any value to edit it. Below each input you'll see:

• A character counter. It turns red if you exceed the allowed length, but you're not blocked from saving — it's a warning.
• An "overwritten" badge if a later upload replaced the value. Hover to see the previous value, click the curved arrow to revert.

Multilingual fields

Some fields (descriptions, marketing copy, allergen text, etc.) accept multiple languages. You'll see a language dropdown on the left of each row. Click + language to add another translation, or the × on a row to remove it.

Mandatory fields

Required fields with empty values are highlighted in amber. After you click Export and the validation finds them missing, they turn into a stronger red. The amber/red clears as soon as you type a value.

Search and jump

• Press / from anywhere on the page to focus the search bar at the top of the editor. Type to filter; matching rows highlight and section headers show match counts.
• Press 1–9 to jump straight to that section number. (Sections 10–17 don't have a number key — scroll or click.)

7 Comparing against a loaded article (compare mode)

Once you've picked a Customer / Project (and signed in if needed), the editor watches the current mapping's primary key — the (GTIN · GLN · Target Market) triple — and quietly probes the connected organisation. When all three values are present and the article already exists upstream, a green Item ✓ found in connected organisation badge slides in just above the attribute accordion, with a small preview showing the unit descriptor and the German descriptionShort the tenant currently has on file.

The same auto-probe runs as you type: changing the GTIN, the information-provider GLN, or the target market triggers a fresh existence check after a short debounce — no clicks needed. A red Item not found chip means you're about to create a new article in that tenant; the green chip means you're about to update an existing one.

Loading the existing article

The found-status row carries a Load Article button. Clicking it fetches the full CIN-XML for that primary key from the tenant, parses it into the same canonical shape your AI extraction produces, and switches the editor into compare mode: every attribute table grows two extra columns, and a sticky compare banner drops in above the accordion with a live diff counter and a Stop comparing exit verb.

The CIN-XML fetch takes 2–10 seconds for a typical record (the upstream renders the full GDSN document on demand); the button shows Loading… and escalates to a spinner past ~1.2 s, but the lookup chip stays visible so you can keep working.

The four-column compare table

Each section in compare mode renders a single 4-column table:

Rows where Source disagrees with Target are highlighted in red and counted in the banner; rows that already agree are rendered plain so the eye lands on the changes.

Per-row verbs

• Take — copies the Source value into the Target. The arrow direction is Source → Target: Take is your "yes, my extraction is correct, this should overwrite the byrd record on the next upload" confirmation. The loaded item mutates in place and the row turns into a green ✓ Taken chip.
• Skip — keeps the byrd-original value and accepts the diff. Use this when the existing tenant value is the canonical one (e.g. a manual override the team applied upstream). The row turns into a grey ✓ Skipped chip.
• Undo — appears next to either chip and rolls the row back one step (Take and Skip are journaled, so multiple consecutive actions on the same row can be undone in order). The hover-tooltip previews the value the undo would restore.

Bulk verbs

• Take all in section / Skip all in section — buttons that appear next to the chevron of every section header that still has unresolved diffs. Apply the verb to every remaining diff row in that section, then jump focus to the first remaining diff in the next section.
• Stop comparing — three buttons in the banner. Skip all walks every remaining diff and reverts loaded to byrd-original; Take all copies every Source value into the loaded item; Fast-forward copies only the diffs that haven't been touched yet, leaving Take/Skip decisions you've already made alone.

Auto-propagation while editing the Source column

Compare mode treats your mapping edits as live opinions. Every keystroke or radio change inside a Source cell is mirrored into the loaded item in the background, the row's diff status re-evaluates immediately, and the Action column toggles between Take/Skip and the resolved chip without a re-render. This means: tweak the Source until it's right, and the corresponding Target side updates with you — no extra Take click required.

Languages-filter and the diff classification

The Languages: DE / FR filter from the upload toolbar (see §4 above) also applies to the compare-mode diff. Only entries in your selected languages count toward "is this row a diff?" — so a tenant article carrying DE+FR+EN+IT entries no longer marks descriptionShort as a diff just because it has extra languages your mapping doesn't. Multi-language values still display in full on the Target side; the filter only governs the diff judgement and the resolution counter.

Reconciliation keyboard shortcuts

Compare mode adds a small set of vim-flavoured keys for walking diffs without the mouse: T takes the focused row, S skips it, J/↓ moves focus to the next unresolved diff, K/↑ goes back, and Enter stages the resolved article into the export queue. The full list lives in §12 below (or press ? for the in-page cheat sheet).

Stopping the comparison

The compare banner's × exits compare mode in two flavours: Discard takes drops every Take/Skip you applied and reverts the editor to your raw mapping; Keep takes lands the resolved loaded item as the new authoritative mapping and closes the banner. Either way, the green found-status row reappears so you can re-load the article later if needed.

8 Validation & missing fields

Empty required fields are highlighted in amber the moment you open the section, and each accordion header carries a ⚠ N pill on the right showing how many required fields in that section are still empty. Hover the pill for the list of field names. There is no global aggregate counter above the editor — the per-section pills are the single source of truth so the count sits where the action lives.

If you click Download CIN XML while there are still empty non-key mandatory fields, an overlay appears asking you to confirm:

• Cancel — closes the overlay and jumps to the first missing field. Recommended.
• Export anyway — generates the XML even with the gaps. Useful for partial drafts.

9 Exporting

Export verbs all live inside the queue panel (open it from the Queue chip in the header, or press ⌘/Ctrl + Shift + Q). The queue panel header has one primary green button and an overflow (⋯) menu next to it.

Upload to organisation — the main flow

The primary green Upload button pushes every queued article (one CIN-XML per item) to the organisation currently picked in the Customer / Project drawer. The flow is a two-stage HTTP cycle per item:

1. POST {base}/gatherings — multipart upload of the CIN-XML, returns a gatheringKey.
2. POST {base}/imports with {gatheringKey, path} — asks the tenant to ingest it.

The destination tenant is decided server-side from the customer's .env section: organisations under ## Test Organisation and ## app.byrd.io Customers go to the BYRD API; organisations under ## m.PIM API Customers go to the m.PIM API. Authentication uses your existing HTTP-Basic credentials for that organisation (the same slot used for Test Connect and Item Lookup).

Queue cards stay visible after a successful upload and are badged ✓ UPLOADED (BYRD) or ✓ UPLOADED (m.PIM) so you have an audit trail in the same session. Failed items get a red ✗ upload failed badge with the upstream error in the tooltip — fix the problem and click Upload again; already-uploaded items keep their green badge.

Download CIN XML Overflow

In the queue panel's overflow (⋯) menu, Download CIN XML (also ⌘/Ctrl + S) ships a single CIN 3.1 XML file bundling every queued article (one transaction per product). Use this for offline review, partner hand-off, or any case where you want the XML on disk instead of pushed into a tenant.

Clear queue Overflow

Also in the overflow menu. Empties the queue after a confirmation prompt — your current article mapping is not affected, only staged items are removed.

10 Working on multiple products (the queue)

You can stage multiple products in a single export by adding each finished product to the Export Queue:

1. Finish editing the current product.
2. Click Add to Queue (or press ⌘/Ctrl + Enter).
3. Open the ⋯ more actions menu next to it and pick Start new article for the next product.
4. Repeat. When you're done, click the primary green Upload button in the queue panel to push every queued article into the connected organisation, or pick Download CIN XML from the queue overflow menu to bundle them into a single XML file on disk.

The Queue chip in the header shows the count. Click it (or press ⌘/Ctrl + Shift + Q) to open the side panel. Each queue card shows a status badge and a Remove (×) button:

• ✓ ready — every required field is filled; safe to upload or download.
• ⚠ N missing — N non-key required fields are still empty. Download CIN XML will warn but can be forced; Upload runs once they're filled.
• ✗ PK missing — one or more of GTIN / GLN / Target Market is empty. Hard-blocks both Upload and Download until you fill the gap.
• ✓ UPLOADED (BYRD) / ✓ UPLOADED (m.PIM) — the article was pushed through /gatherings + /imports successfully. Hover for the gathering key; check the destination organisation to verify it landed.
• ✗ upload failed — the upstream rejected this item. Hover for the exact error.

Uploaded cards stay in the queue on purpose so the badge keeps acting as a session audit trail. Use Clear queue from the overflow menu when you're ready to start a fresh batch.

The queue persists across page refreshes — you won't lose your work if you close and reopen the tab.

11 Image lightbox

Click any image thumbnail in the material grid to open it in full-screen. The lightbox supports:

• Navigate between images: click the chevrons or press ← / →.
• Zoom: + / - to zoom in/out, 0 to fit, or use the toolbar buttons.
• Pan: click and drag the zoomed image.
• Close: press Esc, click the ×, or click the dark backdrop.

PDFs don't open in the lightbox — they open in a new browser tab.

12 Keyboard shortcuts

Pressing ? on the page opens this same list inside the app (the Help → Keyboard shortcuts cheat sheet).

Navigation & search

Global

Reconciliation (compare mode)

Active only while a loaded item is being compared — used to walk per-row diffs without reaching for the mouse.

Image lightbox

13 Tips & things you might wonder about

14 Mini-glossary

GDSN

Global Data Synchronization Network — the GS1-run system that retailers and brands use to exchange standardized product master data.

GS1

The not-for-profit standards body behind barcodes, GTINs, GDSN, and most of the supply-chain identifiers you'll see in this app.

GTIN

Global Trade Item Number — the digits encoded by a product barcode. Used as the primary key for products. Always 14 digits in GDSN, zero-padded if shorter.

GLN

Global Location Number — a 13-digit identifier for a company or warehouse. Sender and receiver of GDSN messages are identified by GLN.

CIN

Catalogue Item Notification — the specific GDSN XML message format this tool produces. Version 3.1 is current.

BYRD

The byrd PIM tenant (app.byrd.io in production, BYRD_TEST for the playground). Organisations under ## Test Organisation and ## app.byrd.io Customers in .env route through the BYRD API. Upload to organisation ships CIN-XML straight into the picked tenant via its /gatherings + /imports endpoints.

m.PIM

Markant's PIM platform. Organisations listed under ## m.PIM API Customers in .env route to the m.PIM API instead of BYRD. Upload to organisation uses the same two-stage /gatherings → /imports flow there. (Replaces the legacy "Export to MPIM" verb and its /api/export-mpim endpoint, both retired.)

Module

A self-contained block of GDSN attributes inside the CIN XML — e.g. tradeItemMeasurementsModule for dimensions, nutritionalInformationModule for nutrition facts. The 17 editor sections roughly map to modules.