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 Name	Description	Mandatory
classification_code	The 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_code	The code of the parent classification. To create a top level classification, the parent code must be "root".	Yes
active	The 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:

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 Name	Description	Mandatory
document_code	The 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_code	The 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).
active	The 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_code	The 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.

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 Name	Description	Mandatory
sku_code	The 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_code	Code of the document to which the variant is associated. (A variant cannot be orphaned via an import).	Yes
active	The 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.

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 Name	Description	Mandatory
media_classification_code	The 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_code	The 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
url	The 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)
external	Indicates 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.

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.

Medias upload process

The medias upload process is based on a set of rules and mechanisms to ensure both efficiency and compliance with bests practices. Here are the details.

Importing and validating URLs

When importing media, each URL is subject to a preliminary check to validate its existence. This validation is performed by means of an HTTP HEAD request on each URL. This request confirms that the file exists on the remote server, without downloading its content.

This HEAD request must return a response with HTTP code 200 within a maximum of 5 seconds in order to be considered valid.

Invalid URLs (timeout, HTTP error response, etc.) are identified and excluded from the download process. The report generated at the end of the import indicates the status of each URL (valid or invalid).

Asynchronous media download

Validated URLs are then queued for download. This process is managed entirely asynchronously. Downloads are executed via HTTP GET requests and adhere to the following principles:

Remote servers must be able to respond within 5 seconds to avoid interruptions.
A limited number of simultaneous connections is maintained to conserve system resources and avoid overloading.
Each downloaded file is stored in the system and immediately goes through a thumbnail generation process. This process is also asynchronous
Volumes must comply with the limits specified in the Fair use[Fair use] section.

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 Name	Description	Mandatory
source_code	The code of the parent object.	Yes
target_code	The 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.

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 Name	Description	Mandatory
attribute_code	The code of the attribute (list type only) to which the value_code will be associated.	Yes
value_code	The 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:

Quick Look - Import a list of values associated with a single select or multiple select attribute

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 Type	Description	Example
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
Numbers Integer Decimal	Number attributes must use the format used for numbers in the import file. Possible formats: 00.00 (default) 00,00
Date	Date attributes must be in the format used for dates in the import file. Possible formats: yyyy/mm/dd dd/mm/yyyy (default)
Hour	Time attributes must be in the format used for time in the import file. Possible formats: hh:mm:ss
Yes / No	Attributes that require a single value out of two options must be in boolean format. Possible formats: true / false yes / no
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 ( \| ).

🚧
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.

👍

Enclosures and Delimiters

Import Files

Classifications

🚧

Example

Documents

🚧

Example

Variants

Example

Assets

🚧

Example

Medias upload process

Importing and validating URLs

Asynchronous media download

Thumbnails for Media Hosted on External Servers

Links

🚧

Example

List of values

🚧

Example

Attribute Columns

🚧Handling the year 1900 with Excel

🚧
Handling the year 1900 with Excel