File Format Reference

Import files are defined by specific columns, according to their file type (unless Mapping is applied).

When imported, the files are interpreted as:

  • lines - the objects to import (documents, assets, etc.) and
  • columns - the characteristics of the objects (document_code, document_name, etc.).

👍

You can download an automatically-generated import file template from an import profile.

Enclosures and Delimiters

  • Data enclosures - Text attributes must be enclosed within quotation marks. If an attribute itself contains quotation marks, they must be doubled so they're not considered the beginning or end of the attribute. Example: "Shoe type: ""Sneakers"""

  • Delimiters - A single character that indicates a separation between values (your attributes). If an attribute contains a delimiter, it must be enclosed within quotation marks. Typical delimiters are:

    • lines- Used to indicate individual lines. Possible values: the line break character (/n) made by the Enter key
    • columns - Used to indicate individual columns. Possible values: comma, semi-colon, tab. Note: If an attribute has multiple values, you must use the pipe (|) character between the values (instead of a comma).

Import Files

The following sections describe the standard columns for Quable PIM import files.

Classifications

🚧

  • Classifications must be imported in hierarchical order, from top to bottom.
  • A line must always have a parent_code that has already been created in the file or that already existed before the import.

The templates generated from an import profile with data type = Classifications will always have the following columns:

Column NameDescriptionMandatory
classification_codeThe unique code of the classification.

If an import file contains duplicates (2 lines with the same classification_code) only one will be taken into account.

In order to avoid errors and unexpected results, be sure to verify that your import file does not contain duplicates.
Yes
classification_parent_codeThe code of the parent classification.

To create a top level classification, the parent code must be "root".
Yes
activeThe status of the classification.

Possible values:

  • 0 - the classification is inactive and not available/visible in searches, but is present in the PIM.
  • 1 - the classification is active.
No

If the column is:

  • absent, there will be no change.
  • present and the cell is empty, the value will be ignored or replaced with 0 (depending on the import profile settings).
<attributes>Individual attributes and their values.No

If the column is absent, there will be no change.

Example

This is an example of an import with three classifications:

350
  • folder_6 - An active, first-level classification
  • folder_7 - A first-level, archived classification
  • folder_8 - An active, second-level classification in the folder_products classification

Documents

🚧

Column headers for text attributes must specify the locale in parenthesis next to the code. If the locale is not present for a column that requires it, the import file will be rejected.

Examples

  • single locale - "toto (fr_FR)"
  • multiple locales - "toto (fr_FR)"; "toto (en_GB)"

Templates generated from an import profile with data type = Documents will always have the following columns:

Column NameDescriptionMandatory
document_codeThe unique code of the document.

If an import file contains duplicates (2 lines with the same document_code) only one will be taken into account.

In order to avoid errors and unexpected results, be sure to verify that your import file does not contain duplicates.
Yes
classification_codeThe code of the level within the target classification where the document will be located.No

New documents
If the column is:

  • absent - the document is created as a orphan.
  • present and the cell is empty - the document is created orphan.

Updating existing documents
If the column is:
  • absent -there will be no change.
  • present and the cell is empty - the value will be ignored or replaced with 0 (depending on the import profile settings).
activeThe status of the document.

Possible values:

  • 0 - the document is archived and not available/visible from searches and classifications, but present in the PIM.
  • 1 - the document is active.
No

If the column is:

  • absent -there will be no change.
  • present and the cell is empty - the value will be ignored or replaced with 0 (depending on the import profile settings).
attribut_set_codeThe code of the attribute set to apply to the document.No

If the column is:

  • absent -there will be no change.
  • present and the cell is empty - the value will be ignored or replaced with 0 (depending on the import profile settings).
<attributes>Individual attributes and their values.No

If the column is absent, there will be no change.

Example

This is an example of an import with two documents with an empty cell option = Replace.

350
  • ref_12345 - An active, orphaned document with no attribute set.
  • ref_12346 - An active document with the product_food attribute set in the folder_products classification.

Variants

Templates generated from an import profile with data type = Variant will always have the following columns:

Column NameDescriptionMandatory
sku_codeThe unique code of the document.

If an import file contains duplicates (2 lines with the same sku_code) only one will be taken into account.

In order to avoid errors and unexpected results, be sure to verify that your import file does not contain duplicates.
Yes
document_codeCode of the document to which the variant is associated. (A variant cannot be orphaned via an import).Yes
activeThe status of the variant.

Possible values:

  • 0 - the variant is archived and not available/visible from searches and classifications, but present in the PIM.
  • 1 - the variant is active.
No

If the column is:

  • absent -the variant is created as active (new variant) or there's no change (existing variant).
  • present and the cell is empty - the value will be ignored or replaced with 0 (depending on the import profile settings).
<attributes>Individual attributes and their values.No

If the column is absent, there will be no change.

Example

This is an example of an import with two variants linked to the ref_12345 document.

350
  • sku_123 - An active variant.
  • sku_124 - An archived variant.

Assets

🚧

Quable PIM does not have limitations for asset formats, however we recommend against using large formats. If you do, their weight should not exceed 200Mb.

Templates generated from an import profile with data type = Asset will always have the following columns:

Column NameDescriptionMandatory
media_classification_codeThe code of the asset classification in which your asset will be located.

If no value is present, the asset will be classified in the DAM classification, level 0. Note: assets classified at level 0 are not visible.
No

If the column is:

  • absent -the asset is created as active (new asset) or there's no change (existing asset).
  • present and the cell is empty - the value will be ignored or replaced by DAM (depending on the import profile settings).
media_codeThe code of the asset.

If an import file contains duplicates (2 lines with the same media_code) only one will be taken into account.

In order to avoid errors and unexpected results, be sure to verify that your import file does not contain duplicates.
Yes
urlThe URL of the asset.

Once an asset has been uploaded, specifying the URL in the import file is no longer mandatory.
  • Yes (new assets)
  • No (existing assets)
externalIndicates if the asset is stored outside the Quable PIM DAM (the PIM then only accesses it in consultation).

Possible values:

- 0 (yes)
- 1 (no)
No
<attributes>Individual attributes and their values.No

If the column is absent, there will be no change.

Example

This is an example of an import with three assets.

350
  • asset_12345 - An asset to upload to the PIM in the folder_assets classification.
  • asset_12346 - An asset in the folder_assets classification (no upload).
  • asset_12347 - An existing asset with the empty cell option = Ignore. The URL and classification will not be changed.

Thumbnails for Media Hosted on External Servers

Quable PIM only generates thumbnails for media hosted on Quable's servers. If media is hosted on external servers (such as a CDN), it is necessary to provide the URL of the thumbnails.
To achieve this, the Asset document type must have a text attribute with the code thumbnail_external_url.
There are two ways to create assets and assign them a thumbnail:

  • via import
  • via API v4:
--location '<http://quable.docker/api_1.php/assets>'
--data '{
    "code": "media_code",
    "name": "media name",
    "active": true,
    "classification_code": "classification_code",
    "media_url": "url_media",
    "external": true,
    "thumbnail_external_url": "url_thumbnail"
}'

Links

🚧

We recommend creating individual import profiles for each link type and using one import file for each type.

Templates generated from an import profile with the data type = Links will always have the following columns:

Column NameDescriptionMandatory
source_codeThe code of the parent object.Yes
target_codeThe code of the child object.Yes
<attributes>Individual attributes and their values.No

If the column is absent, there will be no change.

Example

This is an example of an import with two links using an asset-document link import profile.

350
  • asset_12345 - An asset to link to the ref_12345 document.
  • asset_12346 - An asset to link to the ref_12346 document.

List of values

🚧

To import values for Single choice selection list or Multiple choice selection list attributes, you must reference the attribute code, the value code, and the translations of the values to import.

Templates generated from an import profile with the data type = List of values will always only have the following columns:

Column NameDescriptionMandatory
attribute_codeThe code of the attribute (list type only) to which the value_code will be associated.Yes
value_codeThe unique code of the value.Yes
value_label (xx_XX)The interface label of the imported value_code. This value can be imported in all of your data languages.No (but highly recommended)

Example

This is an example of an import of one list with two predefined values (and translations), and an additional value for an existing list.

Find out our Quick Look tutorial:

350
  • season_summer - An entry in the Season list with translations in French and English for summer.
  • season_winter - An entry in the Season list with translations in French and English for winter.
  • size_m - An additional entry in the existing Size list.

Attribute Columns

You can import values for the attributes of your classifications, documents, variants, assets, and links,

Templates generated from an import profile also include one column per attribute, designated by their codes. These columns are not mandatory for importing objects.

Each type of attribute must respect the following rules:

Attribute TypeDescriptionExample
Text
  • Simple text
  • Multiline text
  • HTML text
Text attributes can be imported with translations by individual columns per data language and specifying the ISO code for the language.

Note
The following attribute types must not include an ISO code because they are not translatable:

  • Simple text not translatable
  • Raw
250
Numbers
  • Integer
  • Decimal
Number attributes must use the format used for numbers in the import file.

Possible formats:
  • 00.00 (default)
  • 00,00
100
DateDate attributes must be in the format used for dates in the import file.

Possible formats:
  • yyyy/mm/dd
  • dd/mm/yyyy (default)
100
HourTime attributes must be in the format used for time in the import file.

Possible formats:
  • hh:mm:ss
100
Yes / NoAttributes that require a single value out of two options must be in boolean format.

Possible formats:
  • true / false
  • yes / no
100
List of values
  • Single predefined value list
  • Multiple predefined value list
Attributes for value lists must be in the following format:

  • column header - the attribute code
  • column - the codes of the predefined values to apply

You can have several value codes, separated by a pipe character ( | ).
100

🚧

Handling the year 1900 with Excel

The year 1900 is incorrectly handled by Excel, so we advise you to use 1970 if you need to initialize dates in the past.