1 of 25

Ergonode transfer

This doc provides an overview of our CSV files format.

Ergonode transfer allows you both to fetch the data to your external system via the export and to populate the Ergonode with your data via the import.

Import and export files are symmetrical which means that the same standard applies to the files created by the Ergonode and the files used for importing data.

Overview

Files format

Overview of the import and export files format

The entire format is represented as an .zip archive containing the following .csv files.

Only zip-archived files are processed properly in case of an import - a simple .csv file upload won't work.

Files within the archive must be named accordingly as in the documentation below.

The maximum archive size is 250 MB.

The maximum single file size within the archive is 1000 MB.

Columns are separated using ","(comma) or ";"(semicolon) separator depending on the configuration.

Files have to be UTF-8 formatted.

Cell value needs to be escaped with the " sign if it contains a column separator. "sku1,sku2" - forcomma separator

"the ; sign is called semicolon" - for the semicolon

The files are placed in the zip archive as top-level entities. Those should not be placed in a subdirectory within the archive - an often mistake for MacOS users - when using right-click menu on a directory containing files and using the option Compress "directory" which does just that.

Below you can find an example of import data.

Please refer to a specific file description for more details.

products.csv

This file can be used to: Create new products, make changes to existing ones, add variants to products with variants, and add products to a grouping product. Leave the attribute value empty to also delete its value in PIM.

In the example, some values are collections(_children, _categories, multiselect_attribute, etc) separated by semicolons.

If your column separator is semicolon as well the CSV file should contain those values escaped with " sign to tell the importer that the value represents a single column i.e. "option_code_1,option_code_2".

Example:

* Note in the above example columns not starting with _ prefix represents product attribute values. Each header name represents an attribute code identifying this Attribute and the cell contains the value.

text_short_description text attribute represented by the text value
textarea_description textarea attribute represented by the text value
numeric_size numeric attribute represented by the numeric value
price price attribute represented by the positive numeric value
unit_weight unit attribute represented by the numeric value
date date attribute represented by the date value
select_brand select attribute represented by the Attribute Option Code
multiselect_attribute multiselect attribute represented by the list of Attribute Option Codes separated by a comma
image image attribute represented by the Multimedia Path
gallery gallery attribute represented by the list of Multimedia Paths separated with a comma
file_appendix file attribute represented by the list of Multimedia Paths separated with a comma
product_relation product relation attribute represented by the list of SKUs separated with a comma

multimedia.csv

This file can be used to: Add supported files to Ergonode resources, add media translation, and media alternative text.

Please keep in mind that importing multimedia via HTTPS protocol requires an SSL certificate to be valid, otherwise, you will receive an import error "Can't download media from URL ... "

Note that _name has to contain an extension valid according to the files MIME type.

Example:

_name

_url

_language

_alt

filename.jpg

www.ergonode.com/image1.jpg

en_GB

alternative text

folder/filename.jpg

www.ergonode.com/image2.jpeg

en_GB

tekst alternatywny

categories.csv

This file can be used to: Create new categories, and add category name translations.

column

required

limitation

_code

Max length of 128 chars. Lowercased, alphanumerical and "_" signes are accepted.

_name

Max length of 255 chars.

_language

5 chars LCID language code. Example: pl_PL

attribute_code*

Column header represents existing Attribute Code. Value should be valid according to given attribute type. Example: product_description

In the example, some values are collections(multiselect_attribute, gallery, etc) separated by semicolons.

If your column separator is semicolon as well the CSV file should contain those values escaped(surrounded) with " sign to tell the importer that the value represents a single column i.e. "option_code_1,option_code_2".

In order to import attribute values the attributes need to be enabled in Category attributes. This can be done either by Ergonode UI or via import file category_attributes.csv.

Example:

_code

_name

_language

text_short_description

textarea_description

numeric_size

price

unit_weight

date

select_brand

multiselect_attribute

image

gallery

file_appendix

product_relation_attribute

category_attributes.csv

This file can be used to: Assign attributes as category attributes.

category_trees.csv

This file can be used to: Create a new category tree, and add category tree name translation.

Example:

category_trees_elements.csv

This file can be used to: Create the category tree structure, or change the category branch location in the existing category tree.

Example:

_code

_parent

_category

category_tree_1

category_root

category_tree_1

category_root

category_child

completeness_sets.csv

This file can be used to: Create the completeness set.

* Language is 5 chars LCID language code. Example: name_en_GB.

Example:

_code

name_en_GB

completeness_set_1

Completeness set name

completeness_set_2

Completeness set name

multimedia_folder.csv

This file can be used to: Create a new multimedia folder and the folder tree structure.

Example:

_name

folder_one

folder_one/folder_two

attributes.csv

This file can be used to: Create new attributes, add attribute translations, define attribute type, scope, and other attribute specifications accordingly.

column

required

limitation

_code

Max length of 128 chars. Lowercased, alphanumerical and "_" signes are accepted.

_type

One of {TEXT, TEXT_AREA, NUMERIC, PRICE, UNIT, DATE, SELECT, MULTI_SELECT, IMAGE, GALLERY, FILE, PRODUCT_RELATION}

_scope

One of {local, global}

_language

5 chars LCID language code. Example: pl_PL

_name

Max length of 255 chars. Lowercased, alphanumerical and "_" signes are accepted.

_hint

Max length of 4000 chars. Lowercased, alphanumerical and "_" signes are accepted.

format

One of existing date formats (see table below)

currency

One of existing Currencies.

rich_edit

One of {true, false}

unit

One of existing Unit Symbols.

unique

One of {true, false}

Available date formats:

Date

CSV Date Format

1999-01-31

yyyy-MM-dd

99-01-31

yy-MM-dd

31.01.1999

dd.MM.yyyy

31.01.99

dd.MM.yy

01/31/99

MM/dd/yy

01/31/1999

MM/dd/yyyy

January 31, 1999

MMMM dd, yyyy

31 January 1999

dd MMMM yyyy

31 Jan 1999

dd MMM yyyy

Example:

_code

_type

_scope

_language

_name

format

currency

rich_edit

unit

text

TEXT

local

en_GB

text

textarea

TEXT_AREA

global

en_GB

textarea

true

numeric

NUMERIC

local

en_GB

numeric

price

PRICE

global

en_GB

price

PLN

unit

UNIT

local

en_GB

unit

data

DATE

global

en_GB

date

yyyy-MM-dd

select

SELECT

local

en_GB

select

multiselect

MULTI_SELECT

global

en_GB

multiselect

image

IMAGE

local

en_GB

image

gallery

GALLERY

global

en_GB

gallery

file

FILE

local

en_GB

file

product_relation

PRODUCT_RELATION

global

en_GB

product relation

custom_fields.csv

This file can be used to: Create new custom fields in the SELECT and MULTISELECT attribute type.

* Note that this attribute must already exist, or the proper attributes.csv file that creates it must be included in the import zip, only SELECT and MULTI_SELECT attribute types support Custom Fields.

Example:

_code

_type

_attribute

custom_field_1_code

IMAGE

attribute_custom_values

custom_field_2_code

TEXT

attribute_custom_values

custom_field_3_code

TEXTAREA

attribute_custom_values

custom_field_4_code

TEXTAREA_RTE

attribute_custom_values

options.csv

This file can be used to: Create options in SELECT and MULTISELECT attribute types. Add options for translations. Add custom field value to already existing custom fields.

* Note in the above example columns not starting with _ prefixes represent custom field code values. Each header name represents a custom field identifying this option and the cell contains the value.

Example:

_code

_attribute

_name

_language

select

name

en_GB

multiselect

name

en_GB

units.csv

This file can be used to: Create a new unit with a name and corresponding symbol.

templates.csv

This file can be used to: Create a new template, and add a translation of the template name.

Example:

_code

_name

_language

code

name

en_GB

templates_elements.csv

This file can be used to: Create a template structure using numeric values representing the position of each template element.

* Language is 5 chars LCID language code. Example: translation_pl_PL.

section_templates.csv

This file can be used to: Create a new section template, and add a translation of the section template name.

Example:

_code

_name

_language

code

name

en_GB

section_templates_elements.csv

This file can be used to: Create a section template structure using numeric values representing the position of each section template element.

* Language is 5 chars LCID language code. Example: translation_pl_PL.

Incremental import

Basic concepts behind the format in terms of importing data

Importing data via provided import files is incremental.

Only present-in-the-file data is changed and the rest is not modified. Consider following:

translation data is changed only in languages provided in the file (column _language)
if a column is not present corresponding resource property is left unmodified
if a Product attribute column is not present values for this attribute are not changed
if a translation column is present and has an empty value the translation value shall be deleted

templates_elements.csv, section_templates_elements.csv, category_trees_elements.csv are exceptions from the above rules. Since those files represent one resource they are attached to the entire resource(template, section, category tree) is imported at once which means if an element is missing in the file the element will be deleted from the resource if was there prior to import.

Import configuration

Name

allows identifying the import profile.

Headers

list of HTTP Headers to be sent by import while downloading Multimedia. For example, those can be used to authorize when requesting multimedia files via URL.

Delimiter

determines what sign divides columns in the imported file.

Include in the imports

a list of resources participating in the import process. If a resource is included in the import and its files are missing in the ZIP archive the import is not started with an error message about the missing file. Only files of included resources will be processed and others in the archive will be ignored.

following options are available:

Attributes - requires attributes.csv and enables support for custom_fields.csv
Categories - requires categories.csv
Category trees - requires category_trees.csv and category_tree_elements.csv
Category attributes - requires category_attributes.csv
Completeness sets - requires completeness_sets.csv
Options - requires options.csv
Products - requires products.csv
Templates - requires templates.csv and templates_elements.csv
Sections - requires section_tempates.csv and section_templates_elements.csv
Multimedia - requires multimedia.csv
Multimedia folders - requires multimedia_folders.csv
Units - requires units.csv

Export configuration

Name

allows identifying the export profile.

Include in the exports

a list of resources generated in the export.

following options are available:

Attributes - includes attributes.csv and custom_fields.csv
Categories - includes categories.csv
Category trees - includes category_trees.csv and category_tree_elements.csv
Category attributes - includes category_attributes.csv
Completeness sets - includes completeness_sets.csv
Options - includes options.csv
Products - includes products.csv
Templates - includes templates.csv and templates_elements.csv
Sections - includes section_tempates.csv and section_templates_elements.csv
Multimedia - includes multimedia.csv
Multimedia folders - includes multimedia_folders.csv
Units - includes units.csv

Languages

limits the exported files to lines containing values only in specified languages.

Delimiter

determines what sign divides columns in the exported file.

Export type

works only within the context of products. Once you edit or add new products only those changes will appear in the export.

Segment

works only within the context of products. Only products available within chosen segment will be exported to products.csv file.

Behavior of variables

works only within the context of products. When textarea value contains variables those will be either exported as #attribute_code or as parsed value.

CHANGELOG

Changelog

The changelog is a list of recent changes to GraphQL API schema.

2024-05-21

completeness_sets.csv file added
templates_elements.csv completeness_set added

2024-05-14

templates_elements.csv new _type values added - divider and note
templates_elements.csv default added. If passed together with it label takes precedence
templates_elements.csv translation_{language} added
templates_elements.csv label becomes deprecated
section_templates_elements.csv new _type values added - divider and note
section_templates_elements.csv default added. If passed together with it label takes precedence
section_templates_elements.csv translation_{language} added
section_templates_elements.csv label becomes deprecated

2024-04-09

attributes.csv unique added

2024-01-25

custom_fields.csv file added
options.csv custom field values added

2023-05-31

templates.csv _name represents from now on the actual Template name rather than the code
templates.csv _language added
section_templates.csv _name added
section_templates.csv _language added

2023-02-22

options.csv _label removed

2023-01-27

category_attributes.csv file added

2023-01-10

units.csv file added

2022-11-09

categories.csv attributes value added

2022-10-19

category_trees.csv file added
category_trees_elements.csv file added

2022-10-11

attributes.csv _placeholder removed
options.csv _name added. It replaces _label column. If passed together with it _name takes precedence

2022-07-14

multimedia.csv _title column added
templates_elements.csv sections column added
templates.csv _language removed
section_templates.csv file support added
section_templates_elements.csv file support added

2022-06-09

products.csv _children column will contain duplicated SKU entries for GROUPING-PRODUCT according to the quantity set for the relation
templates.csv _name becomes deprecated

2022-05-10

templates.csv _language becomes deprecated

2022-03-15

attributes.csv _placeholder becomes deprecated

Breaking changes

The list of recent and upcoming breaking changes

At Ergonode we strive to make your integration process as fluent as possible but from time to time we discover a flaw in the design of the schema or introduce a really cool new feature that is impossible to be provided in a fully-compatible non-breaking way. In such a situation, we will always aim to not break your integration with the new release and provide you with a transition period of approximately 3-months to adjust your consumer. Every such change shall be communicated in the following list.

2024-05-14

Breaking change scheduled for 09-2024

templates_elements.csv label is going to be removed
section_templates_elements.csv label is going to be removed

2022-10-11

Breaking change scheduled for 01-2023

options.csv _label is going to be removed

2022-06-09

Breaking change scheduled for 10-2022

templates.csv _name is going to be removed

2022-05-10

Breaking change scheduled for 07-2022

templates.csv _language is going to be removed

2022-03-15

Breaking change scheduled for 07-2022

attributes.csv _placeholder is going to be removed

attributes.csv

This file can be used to: Create new attributes, add attribute translations, define attribute type, scope, and other attribute specifications accordingly.

column

required

limitation

_code

Max length of 128 chars. Lowercased, alphanumerical and "_" signes are accepted.

_type

One of {TEXT, TEXT_AREA, NUMERIC, PRICE, UNIT, DATE, SELECT, MULTI_SELECT, IMAGE, GALLERY, FILE, PRODUCT_RELATION}

_scope

One of {local, global}

_language

if one of _name, _hint or _placeholder columns present

5 chars LCID language code. Example: pl_PL

_name

Max length of 255 chars. Lowercased, alphanumerical and "_" signes are accepted.

_hint

Max length of 4000 chars. Lowercased, alphanumerical and "_" signes are accepted.

format

if _type column is DATE

One of existing date formats (see table below)

currency

if _type column is PRICE

One of existing Currencies.

rich_edit

if _type column is TEXTAREA

One of {true, false}

unit

if _type column is UNIT

One of existing Unit Symbols.

unique

One of {true, false}

Available date formats:

Date

CSV Date Format

1999-01-31

yyyy-MM-dd

99-01-31

yy-MM-dd

31.01.1999

dd.MM.yyyy

31.01.99

dd.MM.yy

01/31/99

MM/dd/yy

01/31/1999

MM/dd/yyyy

January 31, 1999

MMMM dd, yyyy

31 January 1999

dd MMMM yyyy

31 Jan 1999

dd MMM yyyy

Example:

_code

_type

_scope

_language

_name

format

currency

rich_edit

unit

text

TEXT

local

en_GB

text

textarea

TEXT_AREA

global

en_GB

textarea

true

numeric

NUMERIC

local

en_GB

numeric

price

PRICE

global

en_GB

price

PLN

unit

UNIT

local

en_GB

unit

data

DATE

global

en_GB

date

yyyy-MM-dd

select

SELECT

local

en_GB

select

multiselect

MULTI_SELECT

global

en_GB

multiselect

image

IMAGE

local

en_GB

image

gallery

GALLERY

global

en_GB

gallery

file

FILE

local

en_GB

file

product_relation

PRODUCT_RELATION

global

en_GB

product relation