General File Structure

Example of a sample classifications data file and detailed information about its structure.

The following illustration is a sample data file:

A data file must adhere to the following structure rules:

  • Classifications cannot have a value of 0 (zero).
  • Adobe recommends that you limit the number of import and export columns to 30.
  • Uploaded files should use UTF-8 without BOM character encoding.
  • Special characters, such as a tabs, newlines, and quotes can be embedded within a cell provided the v2.1 file format is specified and the cell is properly escaped. Special characters include:
    \t     tab character
    \r     form feed character
    \n    newline character
    "       double quote

    The comma is not a special character.

  • Classifications cannot contain a caret (^) since this character is used to denote a sub-classification.
  • Use care when using a hyphen. For example, if you use a hyphen (-) in a Social term, Social recognizes the hyphen as a Not operator (the minus sign). For example, if you specify fragrance-free as a term using the import, Social recognizes the term as fragrance minus free and collects posts that mention fragrance, but not free.
  • Character limits are enforced to classify report data.

    For example, if you upload a classifications text file for products (s.products) with product names longer than 100 characters (bytes), the products will not display in reporting. Tracking Codes and all custom conversion variables (eVars) allow 255 bytes.

  • Tab-delimited data file (create the template file using any spreadsheet application or text editor).
  • Either a .tab or .txt file extension.
  • A pound sign (#) identifies the line as a user comment. Adobe ignores any line that begins with #.
  • A double-pound sign followed by SC (## SC) identifies the line as a pre-processing header comment used by reporting. Do not delete these lines.
  • Classification exports can have duplicate keys due to newline characters in the key. In an FTP or browser export, this can be resolved by turning on quoting for the FTP account. This will place quotes surrounding each key with newline characters.
  • Cell C1 in the first line of the import file contains a version identifier that determines how classifications handle the use of quotes throughout the remainder of the file.
    • v2.0 ignores quotes and assumes they are all part of the keys and values specified. For example, consider this value: "This is ""some value""". v2.0 would interpret this literally as: "This is ""some value""".
    • v2.1 tells classifications to assume that quotes are part of the file formatting used in Excel files. So v2.1 would format the above example to: This is "some value".
    • Problems can arise when v2.1 is specified in the file, but what is actually wanted is v2.0 - namely, when quotes are used in ways that is illegal under Excel formatting. For example, if you have a value: "VP NO REPS" S/l Dress w/ Overlay. With v2.1, this is incorrect formatting (the value should be surrounded by opening and closing quotes and quotes that are part of the actual value should be escaped by quotes) and classifications will not work beyond this point.
    • Make sure you do one of the following: change your file format to v2.0 by changing the header (cell C1) in the files you upload, OR properly implement Excel quoting throughout your files.
  • The first (non-comment) row of the data file contains the column headings used to identify the classification data in that column. The importer requires a specific format for column headings. For more information, see Column Heading Format.
  • Immediately following the header row in a data file are the data rows. Each line of data should contain a data field for each column heading.
  • The data file supports the following control codes, which Adobe uses to provide structure to the file, and correctly import classifications data:

    <New Line>

    A new line character is the only supported delimiter between data lines/records in the data file. Typically, you only need to specifically insert these characters when writing a program to automatically generate data files.


    Requests that Adobe automatically generate a unique id for this element.

    In the campaign context, this control value instructs Adobe to assign an identifier to each creative element. See Key.


    Designates that the data column represents the date range associated with the item. See Date.

    Empty field

    Represents a NULL value for the current field. Use this if a particular data column does not apply to the current record.

    PER Modifiers

    Designates that the data column represents a PER Modifier field. See PER Modifier Headings.

Common classification upload issues

The following points illustrate common issues users find when attempting to upload classification files:

Incorrect file format or extension

Classifications require a specific file type to upload successfully. If saved improperly, it throws an error and doesn't process any rows. The error "First column is required to be the key" is likely due to one of the following:

  • Uploading a spreadsheet (.xlsx) instead of a .tab or .txt file: The classification importer does not know how to handle .xls or .xlsx files. When in the Save As dialogue in Excel, set the Save as type toText (Tab delimited) (*.txt) instead of Excel Workbook (*.xlsx). Note: Do not try to change the filename extension when saving the file without changing the Save as type. Doing so can make the attempted filename extension part of the filename. For example, trying to enter fileupload.txt into the filename field while the Save as type is still Excel Workbook creates an Excel Workbook named fileupload.txt.xlsx.
  • Changing the filename extension after saving it as a workbook: Attempting to change any .xlsx extension to .tab or .txt generates an invalid workbook. Only use Excel's Save As function or edit classifications in a text editor such as Notepad or Notepad++.
  • Using uppercase extensions: Uppercase extensions (such as fileupload.TXT) don't work. Rename the file to contain a lowercase extension (fileupload.txt).
  • Incorrect encoding on Apple computers: If using Mac OS, save the file as Windows Formatted Text instead of Tab-delimited Text. Mac computers process text files differently than Windows, which causes the classification importer to throw an error.

Invalid file contents

If your upload file is correctly formatted, the uploader attempts to import as many valid rows as possible. Some common issues with classification data are as follows:

  • Rows that have already been classified: When attempting to upload rows that have already been classified with the same value, the importer returns rows that had no effect. This outcome is expected, as classifications don't reclassify a key value with the same classification. It is more of a notification than an error. It is not anything to worry about if you do not alter all rows within an export file.
  • Missing file header: A classification file without a header doesn't process successfully.
  • Header does not match the variable being uploaded: If you download a classification template for the campaign variable and attempt to upload it to a pageName classification, it fails. Only use export files for the specific variables they were exported from.
  • Line four within the classification file contains data: If you look at any export file, you notice an empty line between the column labels and data. If this blank row is populated with data, the classification import can sometimes fail.
  • A key or classification value contains the value 0: Classifications cannot differentiate the value 0 from a blank cell, so it cannot classify this value. See Using '0' in classifications.
  • The classification file contains commas or special characters: See Classify values using commas.
  • Extra tabs are in the uploaded file: Sometimes when editing classification files, an extra tab can be accidentally slipped in. Each row requires an identical number of tabs to process correctly. To check for extra tabs within the file, do the following:
  1. Open the import file in Notepad and press [Ctrl+A] to select all text.

    Provided each column contains classification data, make sure that there are no extra spaces highlighted after the classification text:

    • This text is what an ideal classification row looks like when highlighted.
    • The empty space after the end of this row would throw an error.
  2. Remove any extra tabs at the end of the file and attempt to upload the file again.
  • Duplicate key values exist in the file: Each key value can only have one classification per column.

    For example, consider the following invalid classification file:

    Key Friendly name No of weeks live

    July campaign

    Internal promotion


    July campaign

    External Ad


    August campaign

    Affiliate promotion


    The July Campaign value can only have one friendly name- this classification file would throw an error upon upload.

  • Subclassifications exist and are incorrectly configured: If subclassifications exist, check the following:
    • All subclassification values have a parent classification value
    • No two subclassifications reference the same parent classification value

If you still have issues uploading a classification file, have one of your organization's supported users contact Customer Care. The Adobe representative can address the issue and provide assistance.