Preparing The Catalog File

The Onboarding Assistant reads your catalog file and uses AI to infer how your data maps to Products and Items in CloudBlue Connect®. A well-structured file gets mapped with higher confidence and needs less manual review, so it’s worth a few minutes of cleanup before you upload. This reference covers supported formats, recommended structure, and the most common issues that slow a run down.

Supported file types

Format	Notes
.xlsx	Recommended. Use a single sheet containing your catalog data.
.xls	Supported for legacy files.
.csv	Supported. Use UTF-8 encoding and a comma delimiter.

General formatting guidelines

• One row per Item. If a Product has multiple variants or SKUs, give each one its own row rather than combining them in a single cell.
• Put column headers in the first row. Don’t add title rows, merged header cells, or blank rows above your headers — these interfere with automatic column detection.
• Use consistent, descriptive column names. Names like ProductId, ProductTitle, SkuId, SkuTitle, and SkuDescription are recognized with very high confidence. Ambiguous or abbreviated headers (like ID or Desc1) are still processed, but are more likely to be flagged for manual review.
• Avoid merged cells and embedded formatting. Plain values map more reliably than merged ranges, colored cells, or embedded formulas.
• Keep one value per cell. Don’t combine multiple attributes (for example, “SKU123 – Monthly – 5 users”) into a single field that a person would need to split apart.
• Use a stable identifier for each Product and each Item. A unique ID column (not just a name) makes it much easier for the Assistant (and yourself) to tell records apart and catch duplicates.

How columns become Products and Items

The Assistant looks for a column that uniquely identifies each Product (a shared identifier across all variants of the same offering) and a separate column that uniquely identifies each Item (an individual, purchasable SKU). For example:

ProductId	ProductTitle	SkuId	SkuTitle	SkuDescription
DG7GMGF0PN5J	Access LTSC 2026	0001	Access LTSC 2026 – Monthly	Monthly subscription, single user
DG7GMGF0PN5J	Access LTSC 2026	0002	Access LTSC 2026 – Annual	Annual subscription, single user

In this example, both rows share the same ProductId and are grouped into one Product with two Items. If your file doesn’t have an obvious grouping column, the Assistant will suggest its best guess and mark it as needing your confirmation on the Mapping screen; it’s worth adding one if you can, since it removes a manual review step.

Recommended columns

You don’t need to match these names exactly, but including columns like these (under any reasonably descriptive header) gives the Assistant the strongest signal:

For Products

• A unique Product identifier
• A Product name/title

For Items

• A unique Item identifier (SKU or part number)
• An Item name/title
• A description
• Any attributes that vary by Item, such as billing period, unit of measure, or user/seat count

Fields you don’t include can be filled in with a fixed value during the Mapping step, or added manually in Connect after creation.

Data quality checklist

Before uploading, check your file for:

• No blank required fields (Product/Item identifiers, names)
• No duplicate identifiers where records should be unique
• Consistent formatting within a column (for example, don’t mix “Monthly” and “monthly” and “1 month” in the same billing-period column)
• No stray characters, line breaks, or leading/trailing spaces in identifier columns
• File size within the upload limit shown on the Source screen

Common issues that trigger manual review

Issue	Effect
No clear grouping column for Products	Assistant guesses and asks you to confirm the grouping before mapping continues
Inconsistent values in an identifier column	May be flagged as a possible duplicate or split into unexpected groups
Missing values in a required field	Blocked at Validation until the value is supplied or the field is remapped
Mixed data types in one column (text and numbers)	Flagged as a type mismatch during Validation

If a run surfaces more manual review steps than expected, it’s often faster to fix the source file and start a new run than to correct everything record-by-record in the wizard.