ETIM xChange
ETIM xChange is the first product and trade item exchange standard fully managed by ETIM International and its community, with a focus on global use. ETIM xChange is based on the European Master Data Guidelines (EMDG) taking into account national exchange standards such as DICO, BMEcat and FAB-DIS). The exchange format is based on JSON, including JSON schema for validation.
Version 1.0 / 1.1
The datapool accepts both 1.0 and 1.1 versions of ETIM xChange. For backwards compatibility reasons, both versions are displayed as ETIM xChange version 1.1.
Current version: 1.1 (23-08-2024)
- Simplified structure in JSON that is logically grouped, based on multiple national exchange standards.
- Generic structure of product data with underlying manifestations; or trade items
- Includes data structure for transporting environmental data such as LCA data in all phases of the life cycle.
- The structure offers the possibility to communicate description fields multilingually.
- Compatible with the latest ETIM-MC structure, including connection types for the Uniform Object Library.
- It has a very flexible structure for all kinds of packaging hierarchy data exchange methods.
The complete documentation of ETIM xChange 1.1 can be found in the downloadsection of ETIM International.
Valid data set
ETIM xChange messages must be validated without errors according to the accompanying scheme. ETIM International offers a validate tool (login required) for this purpose within the website.
Known Issues
Product
- Commodity code at product level
- Alternative product key is missing
Attachments
- Limited number of attachment types
- High/low resolution specification, default mapping to low resolution
Trade item
- Marketing text missing, mapping from ProductMarketingText
- Deeplink missing, mapping from ProductPageURL
- Country of origin missing
Mapping vs datamodel
2BA conforms the data pool to the Dutch standards of Ketenstandaard Bouw en Techniek. The supported exchange formats are mapped to the internal fields of the data model. Some internal fields may differ from the length or type described in the interchange format guideline. We create as much clarity as possible, but there may be differences, exceptions are noted in the mapping.
The code lists used within the exchange format do not always match the code lists from the data model. Always use the code lists associated with the exchange format used. Consult the mappings per code list below:
Mapping ETIM Version
Mapping product status code
Mapping trade item status code
Mapping language code
Mapping packaging code
Mapping attachment ATX code
Mapping item relation code
Mapping surcharges and discounts
Country specific elements
It may happen that a country requires more fields than originally available in the ETIM xChange structure.
The ETIM xChange Country Specific Guideline contains clear examples of how to define these in your data file. Use the CSItemCharacteristics fields as defined in the ETIM guideline section 3.13 from page 50.
| NL CHARACTERISTIC | Name | Explanation |
|---|---|---|
| NL_002-1 | DIN-number |  |
| NL_002-2 | ISO-number | |
| NL_007 | Delivery time | |
| NL_011 | Buying group | |
| NL_012 | Orderable indicator | |
| NL_014 | Fragile on package | |
| NL_015 | Best before date on package | |
| NL_016-1 | Cuttable indicator | |
| NL_016-2 | Maximum cutting length | |
| NL_018 | Code VAT rate | |
Root tree
The ETIM xChange header does not contain an option to specify the exchange format. To recognize the format, the term ETIM_XCHANGE or ETIMxChange must be included in the file name. If this term is missing, the dataset will not be recognized by the import routine.
Points of attention
- NameDataCreator is included in the processing reports.
- SupplierIdGln for the supplier
- Attachments are not imported at header level.
- CatalogValidityStart is not imported.
- The value mentioned first in Languagecode is used for language-dependent fields where no language code is specified. This is in accordance with the BMEcat guidelines. In accordance with ETIM xChange documentation, this is only allowed if only one language is specified. We overrule that business rule. We strongly recommend using language codes.
Type dataset
2BA supports complete or update (mutation) files of ETIM xChange. A complete dataset must contain all active products and trade items. A new complete file overwrites all records in the database. Use CatalogType to define the dataset as a complete or mutation file. Existing product records that are not present in the complete file are marked with status code 130 as “expired product”. Existing trade items records that are not present in the complete file will be deleted.
- CatalogueType FULL: complete file
- CatalogueType CHANGE: mutation file
The advice is to work with complete data sets. By working with complete datasets, the published data remains most similar to your source data. If you have such a large range with many attachments and minor changes, we recommend updating mutation files and periodically publishing a complete file (e.g. yearly)
ETIM classification
Country specific features
From ETIM version 8 it is possible to communicate country-specific characteristics. ETIM xChange 1.0 does not support this functionality. We have made an adjustment to the import schedule in advance to be able to process country-specific characteristics within the data pool.
ETIM version listing
Consult the mapping of the ETIM version versus data model. Within the ETIM xChange documentation it is indicated that the EtimDynamicReleaseDate is mandatory when the ETIM version ‘DYNAMIC’ is specified. We overrule that business rule within the data pool.
Reason no value
If a value cannot be assigned, the data provider has the option to use a minus sign according to the ETIM guideline. Values with a minus sign are not imported. Instead, use one of the following reasons:
- NA; Not applicable (this feature is not applicable in the context of a product in this class).
- MV; Missing value (an alphanumeric function is relevant, but no correct value exists in this ETIM version).
- UN; Unknown (currently the data provider cannot specify a value; but in principle it is possible).
Statuscode
There is also a mutation code at line level within the model. This value cannot be provided with the ETIM xChange standard. There is a mutation code at file level. In addition, a status code has been defined at line level. The combination of both codes is interpreted in the following way:
- Data set type: mutation (CHANGE):
- Read all product records with mutation code: 3 (change).
- Trade item records with status code 125, 126, 94E to transaction code: 3 (change).
- Trade item records with status code 130 to transaction code: 2 (delete).
- Type dataset: compleet (FULL):
- Read all trade items with (model) mutation code: 1 (add/new).
- Read all products with (model) mutation code: 1 (add/new).
Logistics information
Within ETIM xChange, the logistics data is only included in the trade item section.
Points of attention:
- StandardOrderLeadTime is mapped to minimum delivery time. ETIM xChange 1.0 does not support maximum delivery time. This is expected to be possible in a next version. Calendar days are expected as delivery time, not working days.
- Packaging code C62 is imported as ‘unpackaged’ (code NE).
Order price details
When exchanging trade item data, it is extremely important that it is clear how the item can be ordered (minimum order quantity, order multiple and order unit measure), what the price of the item is (price and/or conversion price) and the quantity of that the item (the quantity of use units).
Points of attention:
- The trade item purchase group has been moved to product level.
- Unlike ETIM xChange, the following fields are required:
- Ordering/useunit > mapping model
- Ordering/UseUnitConversionFactor > mapping model
- Pricing/PriceUnitFactor > mapping model
- Pricing/PriceOnRequest > mapping model
- Price/PriceValidityDate > mapping model
Descriptions, brand, serie and type
A good description makes it clear which product it concerns. Customers use these within the (web) catalogue, on transaction messages and within calculations. In addition, the trade item or product can also be found based on the description. The industry standard has two description formats: short and long, and there is also room for an extensive marketing text.
Points of attention:
-
- ETIM xChange 1.0 does not support marketing text for trade items. The ProductMarketingText is mapped to the trade item marketing text.
- ETIM xChange 1.0 does not support trade item level deep links. The ProductPage is copied to the trade item deeplink.
Brand, serie and type
Wholesalers uses the structure of brand, serie, type as a filtering method and search engine optimisation (SEO), for example on their webshop. For this reason these fields are mandatory for each product record. Some manufactures don’t use serie and type grouping. In this case use the value RNV_NA. More information click here.
Hazardous substances and certificates
No specific certificate structure is included within ETIM xChange 1.0. When the type of an attachment certificate is related, a certificate record is generated where possible.
Attachments
By default, the import routine will download an attachment and add it to the product data. Due to the different export formats, the predefined values (ATX codes) are assigned to the attachment type code list.
File hash and OriginalFileSource
The import routine automatically creates a MD5 Hash for each downloaded file. A MD5 Hash makes it possible to determine whether it is a new file or a duplicate. ETIM xChange 1.0 does not include the ability to specify the MD5 Hash and OriginalFileSource.
Points of attention:
- By default, an attachment is downloaded and added to the product data. If an attachment should remain as a reference to the source (URL), this can be arranged outside the exchange format via the parameter.xml KeepMimeURL. Per ATX code you can indicate whether the original source should be retained.
- ETIM xChange 1.0 does not include the option to characterize image-related attachments as low (PPI) or high (PHI) resolution.
- If the AttachmentUri is used, the full path is expected, in accordance with the ETIM Guideline.
- For each attachment, a language code can be specified in which language the content is written using the AttachmentLanguage. If the language code is not specified, the specified header language code is used. excluding the attachment types (images): ATX002, ATX011, ATX014, ATX015, ATX018.
Reference items
In the data model, references and relationships are only mapped at product level, not at trade item level.
Points of attention:
ETIM xChange assumes an implicit unit for a specified quantity; Since it is a trade item (or product) to trade item (or product) relationship, units are assumed (PCE). A part or accessory of a product can be specified with relationship type ‘SELECT.’
