Catalog Upload - Common Fields
Overview
Catalog uploads of common fields files may be full or delta.
A Full Common Fields Catalog Upload replaces all the product records in the system for a supplier. Product records already in the system for that supplier prior to the Full Common Fields Upload are disabled.
A supplier's disabled products in the system will be enabled when they are included in a Full Common Fields Catalog Upload.
A delta upload allows supplier import of common fields for new products or products needing updates for fields in the common fields import, as detailed in this topic.
The Importer accepts ZIP files as well as single CSV Files. In the event that more than one CSV file is contained in the ZIP, the first file will be used to generate the metadata. Rest of the files will than be read in as if they were part of the same file. All CSV files in ZIP must contain the exact same header rows.
See Topics:
Catalog Templates
Catalog Files - Detailed Description
Self-Service Catalog Management Overview
Common Fields Mapped to Product Details Page
BuyerQuest Catalog Upload and Document Statuses
Common Fields Upload Template
Common Fields Support for Catalog-Based Pricing
The Common Fields Catalog file supports multiple prices for the same SKU. Different prices may be associated with different catalogs.
When a SKU has more than one price and is thus included in more than one catalog, the common fields file will include a separate line for each price, as described below.
Users are shown the pricing for the catalog mapped to their Content Group. When a User has access to multiple catalogs, the lowest price is displayed.
The following use cases illustrate scenarios for catalog-based pricing.
| Use Case | SKU | Price | Catalog | Result |
|---|---|---|---|---|
| 1 SKU, 1 catalog | 123 | 1.00 | US | SKU "123" will be uploaded to catalog "US". If the product was tied to different catalogs, it will be removed from those catalogs and will be associated to the catalog "US" |
| 1 SKU, Multiple catalogs | 123 | 1.00 | EU|NA | SKU "123" will be uploaded to catalog "EU" and "NA". If the product was tied to different catalogs, it will be removed from those catalogs and will be associated to the catalog "EU" and "NA" |
| 1 SKU, No catalog | 123 | 1.00 | NULL | If no value is specified for 'catalogs', SKU "123" will be uploaded to the lowest Catalog ID. If the product was tied to different catalogs, it will be removed from those catalogs and will be associated to the the lowest Catalog ID. |
| 1 SKU, 2 prices, Multiple catalogs requires multiple rows in the Common Fields file, one for each unique price/catalog combination |
123 | 1.50 | US | SKU "123" will be uploaded to catalog US with the price of $1.00"EU" and "NA". If the product was tied to different catalogs, it will be removed from those other catalogs. |
| 123 | 2.00 | HI|AK | SKU "123" will be uploaded to catalog "HI" and "AK" with the price of 2.00. | |
| 123 | 3.00 | NY | SKU "123" will be uploaded to catalog "NY" with the price of 3.00. |
Delta Uploads
For delta uploads, all fields except SKU are optional, allowing uploads of files of partial data -- consisting only of data fields needing o be updated.
For delta uploads of partial data, the recommended best practice for a delta partial upload is to include only the columns that need to be updated.
If a required column exists in the partial upload and is empty, the upload will fail.
If an optional column exists in the partial upload and is empty, the value is replaced by the default value for the field.
If the catalog column is not included or is NULL, the price should be updated for all active catalogs for the SKU.
SKUs are handled as described below for the common fields delta file import:
- If a SKU does not exist in the system, the SKU is created only if all the columns and values are present as required for a record in a full import.
- If a SKU does exist in the system, the product will be updated with the values for the SKU for each of the fields included. If a field is not included, the value should remain as is. Validations for data included are the same as for a full upload.
- If validation fails for any field value, the entire row is skipped with a message.
For details on catalog validations, see the Documentation Topic: Catalog Upload Status and Validation Reports.
Catalogs Field and Delta Uploads
For delta uploads of Common Fields, the table below describes the results for a few key scenarios.
| Use Case | SKU | catalog | Result |
|---|---|---|---|
| 1 SKU, 1 catalog | 123 | US | SKU "123" will be uploaded to catalog "US". If the product was tied to different catalogs, it will be removed from those catalogs and will be associated to the catalog "US" |
| 1 SKU, Multiple catalogs | 123 | EU|NA | SKU "123" will be uploaded to catalog "EU" and "NA". If the product was tied to different catalogs, it will be removed from those catalogs and will be associated to the catalog "EU" and "NA" |
| 1 SKU, No catalog | 123 | NULL | If no value is specified for 'catalogs', SKU "123" will be uploaded to the lowest Catalog ID. If the product was tied to different catalogs, it will be removed from those catalogs and will be associated to the the lowest Catalog ID. |
Common Fields Details
| Column Name | Description | Required | Max Length | Sample Value |
|---|---|---|---|---|
| sku | This is the Supplier's Part Number Use the part number that your customer would search for. The same SKU may be associated with different price/catalog combinations. The SKU may be repeated for each combination. |
Yes | 40 | ABC123 |
| name | This is the Name of the product to be listed in the catalog The name should be descriptive, but short. Include descriptors after the name separated by commas. The name will be truncated to 256 characters on import if it is longer than 256 characters. |
Yes | 256 | Ball Point Pens, Black, Box of 12 |
| short_description | This is the Short Description of the product. If the short description is longer than 256 characters, it will be truncated to that length on import. |
Yes | 255 | Smooth feeling of a gel pen with a quick drying, super bold ink. |
| long_description | This is the Long Description of the product Use HTML to format bold, italic, bullets, colors, etc. |
Yes | No limit | Retractable ballpoint pens each feature a bold-point tip, ensuring powerful lines and rich color that is sure to make your handwriting stand out. You'll never again have to worry about wishy-washy lines or weak ink that fades off the page. |
| image | The Product image (a picture, photo or schematic) Specific filename for an image of the product or HTTPS URL. Ideally in the form of SKU.jpg. |
No | N/A | ABC123.jpg |
| manufacturer | This is the Manufacturer of the product. ( if this is the same as the supplier, then simply enter supplier's name) | Yes | No Limit | Acme |
| mfg_part_num | This is the Manufacturer's Part Number (if this is the same as the supplier, then simply enter the part number again) | Yes | 40 | XYZ789 |
| unspsc | This is the products valid United Nations Standard Products and Services Code as an 8 or 10-digit value | Yes | 10 | 11223344 |
| uom | This is the Unit of Measured associated with the product. Not case sensitive. |
Yes | 4 | EA |
| currency | This is the Currency that is used | Yes | 3 | USD |
| lead_time | This is the Lead Time in number of business days | No |
255 | 5 |
| list_price | This is the Supplier's list (pre-contact) price It must be 0 or higher. It is recommended to exclude leading dollar signs. Decimal points should be used instead of commas. Multiple list_price values may be included, each associated with a different catalog. |
Yes | 2 Decimal Places | 1.99 |
| contract_price | This is the Customer's contract price It must be 0 or higher. It is recommended to exclude leading dollar signs. Decimal points should be used instead of commas. Multiple contract_price values may be included, each associated with a different catalog. |
Yes | 2 Decimal Places | 1.54 |
| quantity_increments | This is the fixed quantity increment that the Product should be purchased in | No | 4 Decimal Places | 2 |
| minimum_quantity | This is the minimum quantity that must be purchased at one time for this Product | No | 4 Decimal Places | 5 |
| max_quantity | This is the maximum quantity that must be purchased at one time for this Product | No | 4 Decimal Places | 12 |
| name_<store view> | This is the Name of the product to be listed in the catalog followed by the storeview code which represents the language code. <store view> should be in the format <language code>_<region code>. |
No | 40 | Big stylo bleu |
| short_description_<store view> | This is the Short Description of the product followed by the storeview code which represents the language code. <store view> should be in the format <language code>_<region code> |
No | 255 | Ceci est une excellente plume |
| long_description_<store view> | This is the long Description of the product followed by the storeview code which represents the language code. <store view> should be in the format <language code>_<region code> |
No | No limit | Ceci est un grand stylo bleu |
|
service_type
|
This field helps us to distinguish between a product and a service | No | N/A | 0 or 1 ,'0' (Product) and '1' (Service) Defaulted to 0 if no value present |
| is_qty_decimal | Indicates whether quantities are allowed to be decimal | No | N/A | 0 (No) or 1 (Yes) Defaulted to 0 if no value present |
| in_stock | indicates whether the product is in stock, out of stock, available by quote only, or back ordered | No | 0 (No), 1 (Yes), 2 (Available by Quote Only) or 3 (Back Ordered) | |
| catalogs | a two-letter catalog code for each catalog allows suppliers to specify the catalog(s) the product is associated with and to upload multiple catalogs. All the catalogs a product is associated with must be listed. Each unique price/catalog combination requires a separate line in the file. If no value is specified for this field, the product will be associated with the default catalog, which is the lowest catalog ID. |
No | N/A | US SA|ZZ|NA |
| linked_sku | SKUs of the items that are being linked to the product (the parent item). Multiple SKU values should be delimited by the vertical bar (pipe). Validation of linked SKUs occurs after the common fields file is approved. The validation process for linked_sku confirms that the SKU of the linked item exists in the system for that supplier. SKU values not existing in the system or for non-simple items are skipped. New products being created which will also be associated as linked products should be added to the top of the file so they are created before they are linked. |
No | N/A | ABC123 |
| display_start_date | date that product status is Enabled and product is displayed | No | 01/01/2020 | |
| display_end_date | date product status is Disabled and product is not displayed | No | 03/31/2020 | |
| status | product status is 0 (disabled) null or 1 (enabled) |
No | 1 |
Notes:
Non-keyboard characters should be avoided, such as: ®, ™, ½, “curly quotes”, etc. If a non-keyboard character is needed, the html character encoding should be used, such as ® for a registration mark.
Linked product associations created by the import will show the association as created by Supplier in the Manage Products Grid.
Common Fields Validation and Change Reports
The table below provides details on the validation and change reports generated based on file status.
Generation of reports applies to both Full and Delta uploads.
| File Status | Reason (If Status is Failed) | Validation Report Created | Change Report Created | Notes |
|---|---|---|---|---|
| Failed | A file of the same type is being processed by the System | |||
| Failed | File failed validation | Y | ||
| Failed | File was not approved | Y | Y | |
| Failed | File failed to be updated due to system issues | Y | ||
| Processed Successfully | Y | Y (file will be empty) | File is processed successfully, but is a duplicate of a previously loaded catalog, hence no changes are made. | |
| Processed Successfully | Y | Y | This is the main "success" use case. |
Multi-lingual Common Fields
Multi-lingual product information is enabled by a Common Fields upload. There are three values that are modified for additional languages in the Common Fields file:
- name
- short_description
- long_description
These language-specific columns are added at the end of the common fields file. There is no limit to the number of language specific columns that can be added.
Example - French Store View
name_<store view code> = name_fr_FR
Short description = short_description_fr_Fr
Long description = long_description_fr_FR
Note: An Administrator is able to change these multilingual columns directly from the Admin Control Panel at CATALOGS > Manage Products.