Column headers: names, rules and automatic matching

The first row of your file holds the column names. They are what you connect to fields when you map a configuration, and what Content Uploader checks on every later upload. If your export has no such row and starts with the first item, read it without a header row instead: its columns are then named Column A, Column B and so on (files without a header row).

The rules#

• A column without a name is named by its position. An empty cell in the header row becomes Column C, Column H and so on, as in a file without a header row, and you can map it like any other column. In a workbook, values to the right of the last named column get such names too. Only a first row with no name at all is refused: Row 1 is empty: delete the empty rows above the column names, or, if the file has none, read it without a header row.
• Every name must be different. Two columns called Title are refused, because there would be no way to tell which one you mean. Spaces at the start or end of a name are removed before names are compared.
• A name may be at most 200 bytes (about 200 letters; accented and non-Latin characters take more than one byte each).
• There must be at least one data row under the header.
• A file may have at most 100 columns.

If one of these is broken, the file is not read and the page says The first row must contain unique column names of at most 200 bytes. (or Add a header row and at least one non-empty data row.). Fix the header row and upload the file again. When the cells of row 1 look like values, such as numbers or dates, the message adds Row 1 looks like data, not column names: if the file has no header row, read it again as a file without one.

In a CSV file, a row can also have more values than the header has columns. That row gets the error This row has more cells than the header. and is skipped, while the other rows are not affected. It usually means a stray comma: an unquoted comma inside a cell splits it into two. Put cells that contain commas in double quotes. (A CSV file whose header row ends with empty cells, ID,Title,,, has those columns, named by position.)

Names are matched to fields for you#

When you create a configuration, Content Uploader looks for columns whose names match the destination's fields, ignoring upper and lower case, spaces and punctuation. Publish date, publish_date and PublishDate are the same name to it. A column that matches is chosen for the field at once; you can change it. For example a column Title is chosen for the title, Body for the content, Slug for the slug, Status for the status and Author for the author. Matching looks at the field's name and the label shown in the editor, so Excerpt finds the excerpt. Only letters A to Z and digits count: a name written entirely in other scripts does not match anything automatically, but you can still choose it by hand.

For the record ID, a new configuration suggests a column named ID, External ID, Record ID or SKU (in any case). With none of those, you choose one or let Content Uploader match items by title or slug (choosing the record ID).

Names matter from week to week#

The mapping remembers each column by its exact name. If next week's file has Headline where this week's had Title, and the configuration uses Title, the file is not processed: the page says This file doesn't match the configuration and names Title as missing. Either rename the column back in your spreadsheet or point the mapping at the new name (when the columns change). Adding a column that the configuration does not use is always fine.

Tips#

• Spaces before and after a name are ignored, so Title and Title are the same name (and two such columns count as a repeat). Upper and lower case are kept: Title and title are different names.
• Name the columns you use. A column named by its position keeps that name only while it stays in its place: a column added before it moves it to the next letter.
• Keep the names the same in every file, and keep the order of columns free: the order does not matter.
• If your tool exports names such as post_title or ID, leave them as they are and map them once.
• Avoid putting formulas in the header row.