Manual / Core / Imports

Import sessions

Import sessions are vestl’s safe intake layer for spreadsheet data. They let an operator upload a file, inspect what vestl detected, and run a dry-run preview later without creating or changing live business records.

Use Imports when you need to start from a CSV, XLSX, or Numbers file and want vestl to save the file details, workbook structure, staged rows, source-profile hints, and any parsing or dry-run issues before later approval steps.

What an import session is

An import session is a saved record of one file upload and its dry-run review state.

Each session stores:

the original filename and file format
detected workbook or tab structure
staged source rows for supported dry-run formats
source-profile hints such as Wherefour, Kostner, or Generic
issue counts and diagnostics from intake and dry run
session events such as received, inspected, dry-run started, previewed, or failed
resumable state so the same session can be reopened later

An import session is not a committed import. In the current release, vestl supports intake plus a narrow company dry-run preview. It does not write products, recipes, inventory, companies, or compliance records from that file.

Supported file formats

The upload step accepts these file types:

CSV (.csv)
Excel (.xlsx)
Apple Numbers (.numbers)

If the file extension is unsupported, vestl rejects the upload and records a structured error on the session.

If the file is malformed, vestl keeps the failed session record and stores the failure details instead of silently dropping the upload.

Dry-run format support

The current dry-run preview supports:

CSV (.csv)
Excel (.xlsx)

Numbers uploads still save workbook details and detected table names, but they do not stage row payloads for preview yet. A Numbers dry-run attempt records a clear failure on the session.

What vestl detects during intake

After upload, vestl inspects the file and persists a workbook summary.

For CSV and Excel files, the summary can include:

sheet or tab name
sheet order
detected row count
detected column count
whether a usable header row was found
workbook-level and sheet-level diagnostics
staged source rows preserved for review screens

For Numbers files, vestl saves bundle-level preview details and detected table names when available. Full row preview and mapping for Numbers remain later work.

vestl also runs a source-profile check. Today the shared vocabulary includes:

Wherefour
Kostner
Generic
Unknown

The source profile is a hint, not a commit. It helps later mapping and review steps start with the right assumptions.

Dry-run preview

The current release includes one narrow preview path for Companies.

The dry-run preview:

validates selected staged rows row-by-row
prepares valid company rows for review
marks each staged row as Resolved or Invalid
replaces prior row issues for the selected rows on rerun
updates the session to Previewed on success
records whether the preview started, succeeded, or failed
never creates or updates live company records

Ambiguity review

Ambiguity review helps you decide what should happen when vestl cannot safely match a spreadsheet row to one existing company.

Use this step after a successful company dry run when the preview found rows that still need an operator decision before a later approval screen can proceed.

What the ambiguity review step does:

shows ambiguous matches where vestl found more than one plausible existing company
shows create-new recommendations when no safe existing match was found
keeps skip behavior explicit when a row should stay out of the later approval set
saves the operator choice on the import session instead of writing live company records
keeps blocker counts visible so you can tell whether the session is ready for a later approval step
lets you download error rows for any invalid, unresolved, or skipped blockers that still need attention

This step is still review-only. Matching an existing company, choosing create-new intent, or choosing skip behavior does not create, update, or delete a live company.

Resolution actions

Each ambiguous or blocked row can move into one of these operator decisions:

Resolution action	Meaning
Match existing	You picked the correct existing company candidate for this row.
Create new	You want this row to stay on the path toward creating a new company later, after approval and commit ship.
Skip	You do not want this row included in the later approval set right now.

How to review ambiguous matches

Complete intake, mapping, and the company dry run on the same session.
Open the Company ambiguity review card.
Review the candidate list for each blocked row.
Choose the correct existing company, mark the row as create-new, or use skip behavior if the row should stay out of scope.
Save the decision.
Recheck the blocker counts and, if needed, download error rows for anything still invalid, unresolved, or skipped.

What create-new and skip mean

Create new means the row is allowed to keep moving through the staging workflow. It does not create a live company record yet.
Skip means the row remains visible as intentionally excluded. Skip behavior is durable and inspectable, but skipped rows still stay out of the later approval set until an operator changes the decision.
Invalid rows still need source-data fixes. They remain blockers and should appear in the error export.

Download error rows

Use the error-row export when you need to hand unresolved work back to the spreadsheet owner or audit what still blocks the later approval step.

The download error rows action includes rows that are:

invalid after dry run
unresolved in the ambiguity review step
intentionally skipped

The export keeps issue codes and issue messages so you can see why the row is still blocked.

AI-assisted mapping review

The mapping review workspace helps you confirm which spreadsheet columns should feed the company preview before you rerun the dry run.

What the workspace does:

reads the session’s detected source columns for the selected sheet
suggests a target company field for each source column
shows a confidence label for each suggestion
shows bounded sample values so you can judge whether the suggestion looks right
lets you override any suggestion before rerunning the dry run
saves those overrides on the import session so you can reopen the same session later without re-uploading the file

The mapping review workspace is still part of the no-live-write staging layer. Saving a mapping does not create or update any live company, product, inventory, or compliance records.

What confidence means

Confidence is a review hint, not proof that a mapping is correct.

Use the labels this way:

Confidence	Meaning
High	vestl found a strong header-and-sample match for the target field. Review it, but you usually will not need to change it.
Medium	vestl found a plausible match, but the header, values, or both still leave room for operator judgment. Review sample values before keeping it.
Low	vestl could not build a strong case for the suggestion. Treat these as draft guesses and expect to override them often.

A high-confidence suggestion can still be wrong if the source file uses unusual business language. The operator stays responsible for the final mapping.

What sample values mean

Sample values help you spot whether a suggested mapping fits the real data in that column.

Examples:

a column mapped to company type should show values that look like customer or vendor categories
a column mapped to active status should show values that look like yes/no or true/false flags
a column mapped to company code should show short identifiers, not free-form notes

The workspace shows only a bounded sample, not every row. Use it to make a fast judgment, then rerun the dry run to validate the full staged set.

How overrides work

Overrides let you replace the suggested target field with the one you want.

Operator flow:

Open the mapping review workspace for the sheet you want to preview.
Review the suggested target field, confidence, and sample values for each source column.
Change any target field that looks wrong or incomplete.
Save the mapping.
Rerun the company dry run from the same session.

When you rerun the dry run after saving overrides:

vestl uses the saved mapping first
alias fallback is no longer the main driver for the mapped fields you reviewed
required-field diagnostics reflect the saved mapping you chose
the same upload session is reused, so you do not need to upload the file again

If the mapping payload is malformed or incomplete, vestl keeps the session, records a mapping failure, and leaves the prior saved mapping untouched.

Current company preview rules

The company dry-run preview looks for flexible headers such as:

Customer Name, Vendor Name, or Name
Party Code or Code
Party Type or Type
Notes
Active

Rows are currently previewed against these company fields:

Name
Code
Type
Notes
Active

Types normalize to:

Client
Vendor
Carrier
Internal

The dry run returns row-level issues when required values are missing or malformed.

Accepted columns for the first company preview

The first company dry run accepts flexible header aliases instead of one rigid template.

Company field	Accepted column headers
Name	`Name`, `Party Name`, `Customer Name`, `Vendor Name`, `Client Name`
Code	`Code`, `Party Code`, `Customer Code`, `Vendor Code`
Type	`Type`, `Party Type`, `Customer Type`, `Vendor Type`
Notes	`Notes`, `Note`, `Comments`, `Comment`
Active	`Active`, `Enabled`, `Is Active`, `Status`

Header matching is case-insensitive and trims extra spacing before validation.

What row status means

After preview, each returned row is labeled as either:

Row status	Meaning
Valid	vestl found no row-level blocking issues. The row is still preview-only and not committed.
Invalid	vestl found row-level issues. Fix the row and rerun the preview on the same session.

What validation issues mean

Dry-run issues are persisted diagnostics, not live-write failures. They help you understand why a row could not move forward.

Common issue patterns include:

missing name
missing or malformed company code
missing or invalid company type
invalid active true/false values
empty staged sheets
unsupported dry-run file formats

Each issue can include:

severity
issue code
human-readable message
sheet name
row number
column key

Numbers behavior in the current release

Numbers uploads are supported for intake metadata only.

What works now:

vestl accepts .numbers files into an import session
vestl records workbook or table metadata when it can detect it
vestl preserves failure details if the dry run is attempted

What does not work yet:

Numbers rows are not staged for the company dry run
Numbers dry run does not return row-by-row preview rows
Numbers dry run does not create or update live records

When you run a dry run against a Numbers session, expect a structured failure that explains CSV and XLSX are the currently supported preview formats.

Products import

The products import flow mirrors the company flow — intake, mapping, dry-run preview, ambiguity review — but for finished goods and raw materials. Choose Products / SKUs at intake to send the workbook through the products workflow.

Required workbook columns

The dry-run preview blocks rows that are missing any required field.

Field	Required	What it is
Name	yes	Display name of the product.
Owner Company Code	yes	Existing company code that owns the product (client code, vendor code, or `HOUSE` for in-house). The company must already exist in vestl; import or create companies first if you need to add them.
Product Type	yes	Finished good or raw material. Short labels like `FG` and `RM` are accepted.
Base UOM Code	yes	Symbol of the base unit of measure (`EA`, `L`, `kg`, `gal`, etc). The UoM must exist in vestl’s units table.

Optional workbook columns

Field	What it is
Customer SKU	External SKU from the source system. Used as the highest-precedence match key against existing products.
Product Line Code	Code of the existing product line the product belongs to. Leave blank for products that sit standalone under a client.
Compliance Regime	TTB or None. Defaults to None when omitted.
Target ABV %	Target alcohol-by-volume percentage.
TTB Formula No.	TTB formula number for products under the TTB compliance regime.
Fill volume per vessel (ml)	Per-vessel fill volume (bottle, can, keg, or pouch).
Bottles per Case	Pack count for case BOM derivation.
Description	Free-text description carried into the product record.
Active	`true`/`false` (or `yes`/`no`). Defaults to `true`.

vestl generates SKUs

vestl never accepts a finished SKU from a workbook. SKUs follow a fixed format and are assigned when the approved import is committed. The dry-run preview shows the planned SKU prefix for each row so you can confirm the inferred client, line, and product type before any record is written.

Match strategy

vestl scopes candidate matching to the same owner company — two products with the same name owned by different clients are different products and will not collide. Within that scope, the importer scores candidates by:

Customer SKU exact — highest precedence. A workbook customerSku that matches an existing product’s customerSku is a strong match.
Name exact / alias — display-name equality (or alias equality on the candidate).
Name similarity — token overlap and shared prefix scoring.
Same product line bonus — when the workbook’s product line matches the candidate’s product line, similarity scores get a small bump.

A SKU match with a different display name is still flagged for review so you can confirm the row before committing.

Dry-run validation

The product dry-run checks each row against the owner company, product line, and base unit records in vestl, then reports per-row issues:

Issue	Meaning
Missing owner company code	The `Owner Company Code` cell is blank.
Owner company not found	The code doesn’t match any company in vestl. Add the company first through import or the company wizard.
Owner company inactive	The owner company exists but is inactive.
Product line not found	The product line code doesn’t match any product line.
Product line owner mismatch	The product line belongs to a different company than the workbook’s owner. vestl shows this as a warning so you can confirm the unusual pairing.
Base unit not found	The base unit symbol doesn’t match any unit of measure in vestl.
TTB raw material warning	A raw material row was flagged as TTB-regulated. vestl shows this as a warning.
Invalid numeric value	Target ABV, bottle volume, or bottles per case did not parse cleanly.

Lifecycle phases

Every import session carries a lifecycle phase and a broader status.

Phases

Phase	Meaning
Received	The upload was received and the session record was created.
Inspected	vestl inspected the workbook or bundle and saved the detected structure.
Mapped	The session now carries reviewable source-to-field mappings for a selected sheet.
Resolved	Reserved for later work that resolves row- or reference-level issues.
Previewed	vestl completed a dry-run preview and saved row-level validation state.
Approved	Reserved for the explicit human approval step before any commit.
Committed	Reserved for the final write of approved data into live records.
Failed	Intake or a later stage failed and the session now carries failure details.

Status values

Status	Meaning
Active	The session is still in progress or waiting for the next step.
Completed	Reserved for sessions that reach approved or committed later in the lifecycle.
Failed	The session hit a blocking error.
Abandoned	The session was intentionally left unfinished.

Current release boundary

In this release, intake, mapping, dry run, and ambiguity review can move sessions through these practical states:

Received
Inspected
Mapped
Previewed
Resolved
Failed

Approval and final commit ship later. The current release stops at review.

Review-before-commit safety

The import flow is deliberately conservative.

What happens now:

vestl creates an import session
vestl stores file metadata and workbook summary data
vestl stages CSV/XLSX rows for review
vestl records diagnostics and session events
vestl can preview company rows in a dry run
vestl can persist ambiguity-resolution decisions on the session
vestl lets you reopen the session later

What does not happen now:

no products are created
no recipes or BOMs are created
no inventory is posted
no companies are created
no compliance records are written
no live business records are changed

That boundary is intentional. Intake and preview are the staging layer. Approval and final commit are downstream work.

Redaction and privacy expectations

Source files can contain customer, vendor, or operator data. vestl keeps the broad summary surfaces redacted by design.

Safe summary surfaces show metadata and counts such as:

filename
file format
detected sheet count
row count
issue count
source profile
last error
timestamps

Raw staged-row payloads are not exposed in high-level session summaries and should not be copied casually. Row-level payloads are reserved for detail and review surfaces such as the session detail view, the dry-run preview, and the mapping workspace’s sample-value view.

Diagnostics and inspection surfaces

When a dry run succeeds or fails, vestl saves enough state for later inspection.

Use these places in vestl to investigate:

Session list — redacted session summaries.
Session detail — staged rows, row issues, resolution issues, and event history.
Ambiguity review — saved candidate snapshots and operator decisions.
Error-row export — downloadable rows for remaining blockers.
Event history — lifecycle and failure events.

Watch for these session details:

current phase
row count
issue count
last error

Watch for these event types during preview and ambiguity-review work:

dry run started
dry run previewed
dry run failed
resolution queue built
resolution saved
resolution failed

Field reference

Source profile

A best-fit guess about where the file came from. Use it as a starting point for later mapping, not as proof that the file is ready to import.

Tooltip copy: The source system hint vestl detected from the file name, sheet names, and headers. It helps later mapping start faster, but it does not commit data by itself.

Phase

The current lifecycle stage of the import session.

Tooltip copy: The current stage of this session, from file intake through later mapping, dry-run preview, approval, and commit steps.

Dry-run area

The kind of records the current dry-run preview can check.

Tooltip copy: The first dry-run preview checks company rows only. It is a dry run, not a final import.

Staged rows

Rows held in the import session for later review work.

Tooltip copy: Rows preserved inside the import session for review and dry-run validation. They are not live records yet.

Row status

The preview result attached to each staged row after validation.

Tooltip copy: Valid rows passed the company preview. Invalid rows still need fixes before any later approval step.

Issues

Warnings or errors recorded during intake or preview. Issues can be session-wide, file-level, sheet-level, row-level, mapping-related, or resolution-related.

Tooltip copy: Warnings and errors found during intake, dry run, or ambiguity review. Use the count to see whether the session needs attention before it can move forward.

Resolution queue

The review surface for ambiguous matches, create-new recommendations, and skip decisions after a dry run.

Tooltip copy: The ambiguity review queue shows rows that still need an operator decision before a later approval step can proceed.

Candidate match

A possible existing company that might match the staged row.

Tooltip copy: Candidate matches help you choose the correct existing company when vestl cannot safely decide on its own.

Create-new intent

A saved operator decision that keeps the row on the path toward later approval as a new company.

Tooltip copy: Create new keeps the row in review for a later approval and commit step. It does not create a live company in this release.

Skip behavior

A saved operator decision that intentionally keeps the row out of the later approval set.

Tooltip copy: Skip excludes the row from later approval for now, but leaves the decision visible and reviewable on the session.

Error-row export

A downloadable blocker report for invalid, unresolved, or skipped rows.

Tooltip copy: Download error rows to see which rows still block later approval and why.

Last error

The row-level diagnostics returned by the dry-run preview.

Tooltip copy: Dry-run issues identify the sheet, row, column, code, and message for values that still need correction before a later approval step.

Numbers dry-run support

The current preview limitation for Apple Numbers uploads.

Tooltip copy: Numbers uploads keep workbook metadata and detected table names, but they do not stage row payloads for preview yet.

Mapping review workspace

The review surface that shows suggested source-to-field mappings, confidence, sample values, and saved overrides.

Tooltip copy: AI-assisted mapping suggestions help you review source columns before rerunning the dry run. Confidence is a hint, not approval.

Mapping confidence

How strongly vestl thinks a source column matches a company field.

Tooltip copy: Confidence shows how strong the header-and-sample match looks. High confidence still needs operator review.

Sample values

A bounded set of example values from the source column.

Tooltip copy: Sample values help you judge whether a suggested mapping matches the real data in that column.

Mapping override

An operator-selected target field that replaces the suggested one for this import session.

Tooltip copy: Overrides save your mapping choice on this session and are used the next time you rerun the dry run.

No-live-write boundary

The explicit safety limit around intake and preview work.

Tooltip copy: vestl stores session metadata, staged rows, and dry-run diagnostics here, but it does not create or update live business records yet.

Last error

The most recent blocking failure message on the session.

Tooltip copy: The latest blocking error recorded on this session. Failed preview attempts stay available so you can inspect what went wrong.

Operator expectations

Use the Imports page when you want a safe first pass over a spreadsheet. Expect vestl to tell you what kind of file it sees, how many sheets it found, whether rows were staged for preview, whether AI-assisted mapping found plausible target fields, whether ambiguous matches still need operator review, and whether intake, mapping, dry run, or ambiguity resolution raised warnings or errors.

Do not expect the current release to finish the migration for you. Intake, mapping, dry-run, and ambiguity review are in place first so later approval and final commit can build on an auditable session record instead of a one-shot upload.

Do expect this flow to stay review-first:

AI-assisted suggestions are editable, not authoritative
saved overrides affect the next dry run on the same session
ambiguous matches require an explicit operator decision
skip behavior stays visible instead of disappearing silently
the current release still stops before any live write
an explicit approval gate will come before any final commit path exists