Helpful Guides

Product Loader Overview

It is highly recommended that any related Product Image files are pre-loaded in order to avoid error and warning messages when loading the products

File Formats Supported

  • XLS
    • Separate Excel “tabs” represent each main entity:
      • Category
      • Product
      • Product Associations
      • Feature Swatches
      • Manufacturer
  • XML
    • Structured XML data that represents the main entities as described above

Processing

  • Processing for loading Products is such that any XLS file is converted internally to the BigFish XML format
  • The XML file is then used for actual data loading

References

  • More specific details are available in the spec “BF Admin Module Product Loader.doc”

Product Loader Definitions

Introduction

  • The specification here pertains to the XLS Excel File Format
    • Definitions are the same for the XML format

Category

  • Required to setup the basic catalog Main Category Sub-Category that is used to build the primary navigation for the site
XLS Column Attribute Description
A Category Id An unique identifier for the Category
B Parent Category Id For a main category this should be XX_CATEGORY_ROOT. If a sub category then reference a primary Category-ID
C Category Name The name of the Category, this will appear in the Navigation Bar
D Description The Description, usually displayed on the PLP
E Long Description The Long Description, if required
F PLP Image Name URL reference to the category image
G Additional PLP Text Additional text that can be used to populate data for all PRODUCTS within this Category and be used in the PLP. Typically used if the PRODUCTS do not contain good descriptive information.
H Additional PDP Text Additional text that can be used to populate data for all PRODUCTS within this Category and be used in the PDP. Typically used if the PRODUCTS do not contain good descriptive information.
I From Date Date, used to stage this category. Should not be used during setup.
J Thru Date Date, used to expire this category. Should not be used during setup.

Product

  • This is where all the Products are defined, defining whether they are a FINISHED-GOOD, VIRTUAL, VARIANT and which CATEGORY they are associated with
XLS Column Attribute Description
A Master Product Id

The Master-Product-Id and Product-Id are used to define different types of Products within the loader.

Definitions:
FINISHED GOOD:

this is a stand-alone product that does not have any variations (like Color). For example: a one-size-fits-all Shirt that is only available in White. The customer is NOT prompted for options when adding to cart.

OFBiz: IS_VIRTUAL = “N”, IS_VARIANT = “N” VIRTUAL:

this is a master definition for subsequent Variant products. For example: a shirt is available in different colors and sizes that are prompted on the PDP. The VIRTUAL product defines the master level details that can include descriptions, prices etc.

OFBiz: IS_VIRTUAL = “Y”, IS_VARIANT = “N” VARIANT:

must be associated to a Virtual product, this defines the specific item that can be purchased. For example, RED shirt in size MEDIUM.

OFBiz: IS_VIRTUAL = “N”, IS_VARIANT = “Y”
Rules:

Master-Product-ID is [some-value] and Product-Id is blank, then FINISHED GOOD

Master-Product-ID = Product-ID, then VIRTUAL

Master-Product-ID is [some-value] and Product-ID = [another-value], then VARIANT, where Master-Product-ID is the reference to the VIRTUAL product

Virtual / Variant Notes:

Descriptions, pricing and many other attributes are normally the same for ALL Variants within a single Virtual product. Consider a Shirt description or price. They are both the same regardless of the Variant Color or Size. In these cases, pricing and descriptors should be BLANK for the Variant definitions so that they are inherited from the Virtual product. This is important when pricing or descriptions change since they are only need to be modified on the Virtual product level.

However, in some cases the description may be specific to the Variant (e.g. “This blue shirt is …”). In this case simply define the description on the Variant level.

See examples below.
B Product Id See above
C Category Id Must reference back to the Category-ID in the Category tab
D Internal Name The Internal Name of the product. Used if necessary as an additional information attribute.
Maps to PRODUCT.INTERNAL_NAME, defined as a 255 character string.
E Product Name The primary name for the product. Typically used on PLP and main heading on PDP.
Maps to PRODUCT.PRODUCT_NAME defined as a 100 character string.
F Sales Pitch This attribute and several others, see below, are flexible content descriptors.
As such they can all be repurposed (for example, “Sales Pitch” could be repurposed to “Care Instructions” by changing the appropriate Label). As “content” these fields are unlimited in length and can contain HTML tags to manage styling, if desired. Styling should be delegated to the CSS as much as possible so try to avoid excessive use of HTML tagging in these attributes.
G Long Description Primary Long Description, typically used as the main descriptor in the PDP.
Maps to PRODUCT.LONG_DESCRIPTION, defined as a LONGTEXT attribute.
H Special Instructions See explanation for Sales-Pitch
I Delivery Info See explanation for Sales-Pitch
J Directions See explanation for Sales-Pitch
K Terms/Cond See explanation for Sales-Pitch
L Ingredients See explanation for Sales-Pitch
M Warnings See explanation for Sales-Pitch
N PLP Label  
O PDP Label  
P List Price The List Price for the product.
Q Sales Price The Sales Price for the product
R Selectable Features #1

Selectable Features are those features that define the specific Variant.

For example “Color:Blue” or “”Size:Medium”.

Each Selectable-Feature column controls a specific feature. Multiple values can be defined.

For example:

a shirt is offered in colors Red and Blue as well as sizes Small, Medium and Large.

Selectable Feature #1 “Color: Red, Blue”
Selectable Feature #2 “Size: Small, Medium, Large”

This would create 6 Variant products.
Selectable Features will impact the drop-down selections on the PDP.

Selectable Features are available for faceting.

See examples below.
S PLP Swatch  
T PDP Swatch  
U-X Selectable Features #2 thru #5 See Selectable Feature #1
Y-AC Descriptive Features #1 thru #5

Descriptive features are similar to Selectable Features but do not impact the actual SKU that is being sold. It describes the product.

For example:

Descriptive Feature #1 “Material: Leather”
Descriptive Feature #2 “Style: Wedge”
Descriptive Feature #3 “Heel Height: 6 inches”

Descriptive Features are available for faceting.
AD PLP Image Used as the primary image on the PLP.
Stored as SMALL_IMAGE_URL
AE PLP Image Used as the alternate image display on the PLP. This image is typically displayed on mouse “hover” and will a reverse view.
Stored as SMALL_IMAGE_ALT_URL
AF PDP Image: Thumbnail The initial image used as the thumbnail in the PDP.
Stored as THUMBNAIL_IMAGE_URL
AG PDP Image: Regular The primary image displayed as a default in the PDP.
Stored as LARGE_IMAGE_URL
AH PDP Image: Big Popup The default image used in either a zoom component or the “See Larger Image” link.
Stored as DETAIL_IMAGE_URL
AI-BL PDP Alt Images

Additional sets of images, up to a total of 10 per Product.

The #2 thru #10 images are for additional sets of images used on the PDP.

THUMBNAIL: a PDP thumbnail image, when clicked the main “REGULAR” image will also be displayed.

REGULAR: the primary PDP image.

EXTRA_LARGE: the image used in either a zoom component or the “See Larger Image” link.
BM Product Height Height of the Product. Not currently used other than for informational purposes. Future changes will consider this attribute when calculating shipping charges.
BN Product Width Width of the Product. Not currently used other than for informational purposes. Future changes will consider this attribute when calculating shipping charges.
BO Product Depth Depth of the Product. Not currently used other than for informational purposes. Future changes will consider this attribute when calculating shipping charges.
BP Returnable (Y or N) Is product returnable? Not currently used other than for informational purposes. Future changes will consider this attribute when processing a return.
BQ Taxable (Y or N) Is product Taxable? Will impact how Sales Tax is applied in the cart.
BR Charge Shipping (Y or N) Should this product have shipping charges applied? Will impact cart totals.
BS Intro Date Introduction Date. Typically only used in a LIVE environment to stage Products.
BT Disco Date Discontinued Date. Typically only used in a LIVE environment to remove Products.
BU Manufacturer Id The Manufacturer-ID. Must match an entry in the Manufacturer tab.
BV GOOD_ID (SKU) A “Good Identification”, value for SKU.
BW GOOD_ID (Google) A “Good Identification”, value for Google.
BX GOOD_ID (ISBN) A “Good Identification”, value for ISBN.
BY GOOD_ID (Manu-ID) A “Good Identification”, value for Manu-ID.
BZ PDP_VIDEO_URL URL for any Video to be displayed in the PDP
CA PDP_VIDEO_360_URL URL for any 360 Video to be displayed in the PDP
CB SEQUENCE_NUM This determines how the Product is sequenced within the PLP for the sort option “Most Popular”
CC BigFish Total Inventory Used for BigFish inventory processing, typically to control Stock indicators on the PDP

PRODUCT_ATTRIBUTE with ATTR_NAME = “BF_INVENTORY_TOT”
CD BigFish Warehouse Inventory Used for BigFish inventory processing, typically to control Stock indicators on the PDP

PRODUCT_ATTRIBUTE with ATTR_NAME = “BF_INVENTORY_WHS”
CE Select Multiple Variants on PDP Ability to add multiple products on the PDP using either Checkboxes for each Variant or a Quantity input field. Values are “NONE”, “QTY” or “CHECKBOX”.

PRODUCT_ATTRIBUTE with ATTR_NAME = “BF_INVENTORY_TOT”
CF Product Weight Height of the Product. Used for special case Shipping Charges of heavy items.
CG Check Out Gift Message If set to TRUE then the Show Cart page will offer the entry of a Gift Message for each purchased product. Applicable only to buyable products (Variant or Finished Goods).

PRODUCT_ATTRIBUTE with ATTR_NAME = “CHECKOUT_GIFT_MESSAGE”
CH PDP Qty Min For both the PLP and PDP, the minimum Qty that can be purchased. Override of the system parameter.

PRODUCT_ATTRIBUTE with ATTR_NAME = “PDP_QTY_MIN”
CI PDP Qty Max For both the PLP and PDP, the maximum Qty that can be purchased. Override of the system parameter.

PRODUCT_ATTRIBUTE with ATTR_NAME = “PDP_QTY_MAX”
CI PDP Qty Default For both the PLP and PDP, the default Qty that is displayed. Override of the system parameter.

PRODUCT_ATTRIBUTE with ATTR_NAME = “PDP_QTY_DEFAULT”
CJ PDP In Store Only For both the PLP and PDP, a Y-N indicator that will prohibit purchase and display the In Store Only content.

PRODUCT_ATTRIBUTE with ATTR_NAME = “PDP_IN_STORE_ONLY”

Product Associations

  • This is where all the Associations are managed.
  • Product associations control the “You May Also Like”, “Wear It With” cross sell content in the PDP
  • Associations cannot be made at the Variant level
    • Only Virtual or Finished-Good products can be associated to other Virtual or Finished-Good products
XLS Column Attribute Description
A Product Id The Master-Product-Id that is associated with another Product.
B Product Id To The Master-Product to associate TO.
C Product Association Type

Either COMPLEMENT or ACCESSORY. Note that these associations are loosely defined and can be labeled to whatever suits the business need.

Example: “You May Also Like”, “Wear it With”, “Complete The Look”, “Matching Accessories” etc.
D From Date Effective FROM date. Typically only used in a LIVE environment to stage Associations.
I Thru Date Effective FROM date. Typically only used in a LIVE environment to remove Associations.

Feature Swatches

  • This section sets up DEFAULT swatch images
  • For example: if the PLP needs to indicate which colors are available, then small color “swatches” can be loaded for use as a visual indicator
  • Defaults can be overridden at the Product level
XLS Column Attribute Description
A Feature This is the specific Selectable Feature that the swatch pertains to.
Example: “Color: White”
B PLP Default Swatch URL defining the swatch to be used in the PLP
C PDP Default Swatch URL defining the swatch to be used in the PDP

Manufacturer

XLS Column Attribute Description
A Manufacturer Id A unique identifier for the Manufacturer. Used as a cross reference in the Product tab attribute.
B Name The name of the manufacturer
C Address The address of the manufacturer
D City The city of the manufacturer
E State The state of the manufacturer
F Zip The zip of the manufacturer
G Short Description A short description of the Manufacturer
H Long Description A long description of the Manufacturer
I Profile Image Name URL defining an image to be used on any manufacturer profile page

Examples and Best Practices

Virtual / Variant Product Setup

  • The Product Loader has many ways for Clients to setup Virtual and Variant combinations depending on their business requirements
  • Example #1: best practice, separate rows for Virtual and each Variant Product
Master Product ID Product ID Selectable Feature #1 Selectable Feature #2
P-123 P-123    
P-123 P-123-A Color: red Size: small
P-123 P-123-B Color: red Size: medium
P-123 P-123-C Color: red Size: large
P-123 P-123-D Color: blue Size: small
P-123 P-123-E Color: blue Size: medium
P-123 P-123-F Color: blue Size: large
    • This will create ONE Virtual Product and SIX Variants
    • Benefits are:
      • Product-ID can be defined in the feed file
      • Images can be uploaded for each specific Variant
      • Inventory can be managed for each specific Variant
  • Example #2: minimal definition
Master Product ID Product ID Selectable Feature #1 Selectable Feature #2
P-123 P-123    
P-123 P-123-V Color: red, blue Size: small, medium, large
    • This will also create ONE Virtual Product and SIX Variants
    • Restrictions are:
      • Product-ID will be generated (P123-V-01 thru P123-V-02). So, this format should only be used if this isn’t a problem.
      • Only one set of images can be uploaded. So, this format should only used if the images are used for all Variant combinations.
      • Inventory cannot be managed.
  • Example #3: hybrid definition
Master Product ID Product ID Selectable Feature #1 Selectable Feature #2
P-123 P-123    
P-123 P-123-R Color: red Size: small, medium, large
P-123 P-123-B Color: blue Size: small, medium, large
    • This will also create ONE Virtual Product and SIX Variants
    • Benefits are:
      • Images: the “red” and “blue” set of Variants are separated, so a different set of images can be uploaded for the primary differentiator.
    • Drawbacks are:
      • Product-ID will be generated (P123-R-01 thru P123-R-03 and P123-B-01 thru P123-B-03).
      • Inventory cannot be managed

XML definitions should use the “Example #1: Best Practice” approach.

The above processing best practices apply to the XLS Excel File Format only. When the XLS is pre-processed and converted to XML all data is “exploded” so that the final XML format represents the “Best Practice” approach.

Post Load Considerations

  • Rebuild the SOLR Index:
    • Admin arrow Admin Tools arrow SOLR Indexing
  • Rebuild SEO Friendly URLs:
    • Admin arrow Admin Tools arrow SEO Friendly URL
  • Clear Cache:
    • Admin arrow Admin Tools arrow Clear BigFish Cache
Back to Top

Built by Solveda