Importing, processing and deploying product images

From FluidRetailWiki

Contents 1 Overview 2 Preparing product images 3 Import: adding sources images 3.1 Choosing the best import method 3.1.1 Hot Folder 3.1.2 CSV Import 3.1.2.1 Collecting and organizing product data required for batch import 3.1.2.2 Importing product images 3.1.2.3 Importing product data 3.1.3 XML Import 3.1.3.1 Optional XML Data Feeds 3.1.4 Manual Display Production 3.1.4.1 Add New Product 3.1.4.2 Add and configure Variations 4 Creating interactive merchandising displays 5 Deploying displays to your site. 5.1 Configuring the System for Display Deployment 5.2 Deploying Displays

Overview

This guide is intended to aid the user in the creation of interactive merchandising displays which is comprised of the following steps:

1. Creating/organizing product data and images

2. Importing or entering product data and images into the Fluid Display authoring environment

3. Creating interactive merchandising displays

4. Deploying displays to your site.

Follow these sequential steps to get your product catalog up and running as quickly as possible.

Preparing product images

While interactive displays can accommodate any variety of image sizes, aspect ratios and visual treatments to fit with a given display, the following guidelines should be followed for the best results:

• File Format - Images must be in JPEG RGB format, 72 dpi minimum. Using a CMYK color profile intended for print will result in discolored images.

• Aspect Ratio - Images that do not share the same aspect ratio as the display will be reduced to fit using white padding on either the sides or top/bottom. Aspect ratio will be retained

• Image Placement - Ensure that product images have a consistent amount of padding between the edge of the actual product and the image border.

• Image Treatment - Background colors, drop shadows, etc. should be consistent across all images. White backgrounds are preferable as they blend most easily with the default display background.

• Image Size – The required resolution of source images is determined by the size and the level of magnification in your display template. Ex: If the main display 250x300, and you've specified magnification at 4x (400%) then source images should be 1000x1200. As a general rule of thumb, we recommend uploading images that are 2500px on their longest side to accommodate future template development. During display production, Fluid Retail automatically creates all image sizes necessary for the display.

• File Naming - In general, files should be named using a combination of product ID (style number), variation ID (color code) and view name. If any of these values are not applicable to your products, it's best to include them regardless in order to maximize flexibility down the line. Examples: productId_variationId_viewName.jpg or T501_blue_1.jpg. View names should using something simple like "1, 2, 3" or "view1, view2, view3", which, when sorted alpha-numerically, allow the default view to appear first.

.

Import: adding sources images

Before discussing import methods, it's helpful to understand how Fluid Experience organizes product images and relates them to products. These values are used when embedding displays in HTML, changing product colors via JavaScript, etc.

Product hierarchy:

• Product Id - This should be a unique product identifier or style code. Typically, this code should be free from color or sizing information and this code specifies which product is displayed on a given page. Note: Cannot contain characters that are not valid for file naming. For ex: /, \, @, etc.
  • Product Name
  • Product Category - Optional field. May be helpful for organizing your products. For ex: outerwear, footwear, etc.
  • Display Profile - Optional field. Maps products to desired presentation
  • Variation Id - This is your color id or code. Note: Cannot contain characters that are not valid for file naming. For ex: /, \, @, etc.
    • Variation Name - This is the color name. "Charcoal Black"
    • Swatch color value 1-5 - Optional field. Used to allow the user to navigate between product colors. You can also use images swatches by setting image type to 'swatch'. Ex: #BBBABB.
      • View Name
        • Image Path - This is the filename and location of the source image. Required for CSV and XML import methods. See below*
          • Image type - main|swatch|both Optional field. Default is 'main'

Choosing the best import method

Fluid Experience can be populated using the following methods:

• Hot folder - By and far, this is the easiest method to add images to the Fluid Retail system. It requires that images follow a standard naming convention and are then uploaded to ftp.fluidretail.net where they are automatically retrieved and imported into the system.
• CSV import - This method provides maximum flexibility as CSV spreadsheet is used to associate images to products and add any required metadata such as variation
• XML import - Fluid Retail is provided with an XML feed from a remote system at regular intervals to add new products and colors.
• Manual upload

Hot Folder

Using the hot folder method, a customer names files according to an agreed upon naming convention and FTP the images to root of ftp.fluidretail.net using their standard Fluid Retail login. After the job is started, Fluid Retail will key off image names to correctly associate product images with products, variations and views. The following values are supported in file naming:

• product ID
• variation ID
• view name
• hex value (for swatches)*
• display profile*
• image type*

*Optional

Working with Fluid Retail support, the customer decides on a naming convention that best meets their needs and this is coded into the import script. For display profile and image type, it's possible to preset a default value which will be used in the event the value is not provided in the file name.

Example files:

• T501_blue_1.jpg
• T501_blue_1_swatch.jpg
• T501_blue_2.jpg
• T501_blue_3.jpg
• T501_red_1.jpg
• T501_red_1_swatch.jpg
• T501_red_2.jpg
• T501_red_3.jpg

This naming convention is defined as productId_variationId_viewName_imageType.jpg where imageType is set to 'main' if not specified. This would create two variations within the T501 product (red and blue), each with 3 views and image swatches.

The Fluid Retail system will automatically track the "last modified date" of each image and import only those images which have been added or changed since the script last ran. As with all jobs, it can triggered in the admin tools or scheduled to run at a regular hour. If a single image of a product is modified, Fluid Retail will re-import the entire product. While we cannot detect when an image has been removed (only changed or added), a user could remove an image by deleting it from the FTP and then re-adding an existing image to trigger a refresh of that particular product. Overall, this is not typically a concern as most customer hide and show variations dynamically at runtime using JavaScript. See the following section for more information: Hiding, showing and ordering variation and view thumbnails at runtime

You'll notice that neither Product Name nor Variation (Color) Name can be specified in the file naming.

• If it's important to have Product and Variation Names available in the system, an XML feed could be provided from the e-commerce system which Fluid Retail could retrieve to augment its catalog. This is much more simple than a catalog feed that relies on an XML file only as 1) it does not need to provide a path a source image (not typically known by the e-commerce system) and 2) it need not track what products and/or images have changed in a given period. It can merely send the entire catalog and Fluid Retail will grab the correct information.
• If you plan to use Fluid Experience to render the color thumbnail controls, it may be desireable to provide an XML feed to add these color names. The other option is to display color names in the HTML and integrated with the thumbnail selector using JavaScript. This is also a good option where internationalization is desired. The e-commerce system can present the correct color names depending on the locale and integrate with Fluid Experience using the univeral variation ID.

CSV Import

Collecting and organizing product data required for batch import

Compiling and organizing product data is your first step in creating Fluid Retail merchandising displays via batch.

Click here to download a sample of the CSV file used for importing product data.

CSV import accommodates the following fields:

• product_id
• product_name
• product_category
• display_profile
• variation_id
• variation_name

If a product is available in several colors or variations, create a separate line for each with a shared product_id. variation_id's must be unique per product.

product_id    product_name    variation_name    variation_id    image_path
T036          Nevada          SCARLET           002             T036_002.jpg
T036          Nevada          PACIFIC           443             T036_443.jpg
T036          Nevada          SIENNA            662             T036_662.jpg
T036          Nevada          MERLOT            505             T036_505.jpg

• swatch_color1-5
• view_name

• image_path - This is the filename and location of the source image. Images can be specified in one of two ways:
  • Direct URL – If your images are accessible via a webserver, specify the absolute address where they can be found.

Ex: http://www.mysite.com/catalog/images/redshirt.jpg

NOTE: If you use the Direct URL method, your images MUST be available via HTTP from any public web browser. If your images are behind a firewall, you will need to modify its settings to accept HTTP connections from Fluid Retail server (name: fluidretail.net, IP: 208.75.210.72)

• • FTP Images to ftp.fluidretail.net and specify path/file name – FTP your images to ftp.fluidretail.net using your regular login then specify the image path and file name relative to the FTP home directory. Ex: if you FTP your images to the home directory on ftp.fluidretail.net, a directory path is not necessary. Just specify the image name in the Image Path field.

• Image Type (image_type) – Set this value to "main" to specify that you are uploading a main product image, or to "both" if this image will be used as both the main image and the thumbnail swatch image.

If you already have product imagery for color swatches and want to use them instead of specifying HEX values, follow these steps:

1. Create a line of data specifying the product name, image path, etc. and set the image type to "main".
2. Create a second line of data with identical values as the first except specify the name of your swatch image file for image_path and set the image type value to "thumb".

product_id    product_name    variation_name    variation_id    image_path         image_type
T907          Half Pint       BUBBLE GUM        671             T907_671.jpg       main
T907          Half Pint       BUBBLE GUM        671             T907_671_thumb.jpg thumb

Note: If specifying an image to be used as a swatch, be sure to leave the SWATCH hex values blank.

Importing product images

If necessary, FTP product images to ftp.fluidretail.net. If you specified the URL of your images on your web server, be sure all of your images are publicly available. If you images are behind a firewall, you will need to allow access on HTTP port 80 from fluidretail.net at IP 72.32.131.230 and 72.3.142.206

Importing product data

Import your product data using the following steps:

1. Click ’Import Product Data’ – Located at the top of the application. Click "Upload Import CSV" in lower right. Navigate and select the CSV file on your local machine. Click OK. (Alternatively, you may FTP this file to ftp.fluidretail.net using your regular login credentials. The CSV file will then appear in the file list.)

2. Select the CSV file that you just uploaded.

Choose an import method - There are two ways to import product information:

ADD and UPDATE: Add new products or variations, overwrite and update existing variations

In this mode, the authoring tool adds product and variation data in your import data file to your existing data. No data can be deleted using this method.

TIP: This method is useful if you publish your catalog on an infrequent basis and want to use Fluid Display to help track your product work flow by allowing you to upload partial batches and follow up later with missing images and product data.

For example, you are adding a new variation or a new color, to an existing product. Or, you’ve received a new product photo or have decided to modify the color hex value for existing variation.

In these examples, your data import file should only contain those product variations you would like to add or modify.

DELETE and IMPORT: Delete all existing products contained in the spreadsheet (inc. variations, images and displays) and import new product data.

In this method, the authoring tool first deletes all product data, images and displays for the product IDs in your data file only and then imports the new data. Products that are not contained in your data file are left unchanged.

TIP: This method is useful if you publish or make updates to your catalog on a frequent basis. For the most efficient batch production, make sure that your data file only includes new or modified product data. This way, you’ll only recreate the displays you need.

3. File Preview – You will be shown a data preview. Click "Next" to validate the data.

4. Data Validation – The system will validate the data and display any errors encountered. Typically, errors most often occur when image files specified in the import template cannot be found in the system. It is recommended that your download errors and resolve them before proceeding.

NOTE: If you need to edit your product data file, be sure to edit the original XLS and resave as a CSV. CSV files do not import formatting when opened in Excel. If you open a CSV containing the value "002" in Excel, it will be converted to the number 2.

5. Data Import – If no errors are reported, data import will begin. At this point you may close your browser and check progress by clicking the Jobs panel in the Admin tab.

Once the process is complete, click "Finish". The system should now be populated with the products you listed in the import template.

.

XML Import

When using XML import, the Fluid Retail system will request an XML data file from the customer system via HTTP or HTTPS. Typically, the URL would reference a PHP script or servlet that generates the XML document when requested.

The feed provides the core product data feed as well as paths to high-resolution source images.

The Product Catalog Update feed must return an XML document conforming to the following XML Schema:

http://schemas.fluidretail.net/ProductCatalog.xsd

A sample Product Catalog Update file can be found here:

http://engage.fluidretail.com/TestXML/sampleProductImport.xml

While some fields in the feed are optional, we recommend populating all fields for a given product for best results in automated publishing.

In order to assist the remote system determine which products to send when the feed is requested, Fluid Retail will append the timestamp of the last successful product catalog import to the URL of the feed, in yyyyMMddHHmmssZ format. The Z attribute will indicate the time zone of the Fluid Retail server in the format: "-0600", where time zone is a 4 digit number either plus or minus GMT.

Example: http://productimages.yoursite.com/fluid/catalog?lastSuccessfulRunTime=20090507000000-0600

The remote system would then use this date to determine which products to return (i.e. it would only return products that have been added or changed since the specified date). While it’s possible for the Fluid Retail system to perform a complete catalog refresh each time, this is not desirable and could result in a delay in new products being published as part of large catalogs.

When a product is imported, Fluid Retail will first delete any existing copy of the product (and all its associated data) before re-importing the product. It is therefore necessary to ensure that the product record is complete each time it appears in a feed. If only one variation has been updated, or a single image has been updated, it is necessary to include all variations and all images for that product.

Optional XML Data Feeds

Master Product List - A master product list can be provided to remove outdated or obsolete products from the Fluid Retail system.

A sample Master product List file can be found here:

http://engage.fluidretail.com/TestXML/samplemasterProductList.xml :

The Master Product List feed must return an XML document conforming to the following XML Schema:

http://schemas.fluidretail.net/MasterProductList.xsd

Deployment Confirmation Feed - Upon completion of a deployment job, Fluid Retail can send a list of products that have been successfully deployed to the remote system. The confirmation will be sent as a HTTP POST request via URL.

The POST data will be in one of two formats:

• Comma-delimited

inventoryIds=T501,T243,T234,ANX3

• XML-based

<ProductConfirmation xsi:schemaLocation="http://fluid.com/drive/catalog http://schemas.fluidretail.net/ProductConfirmation.xsd">
<Product inventoryId="Product1"/>
<Product inventoryId="Product2"/>
<Product inventoryId="Product3"/>
<Product inventoryId="Product4"/>
<Product inventoryId="Product5"/>
</ProductConfirmation>

To get started using XML feeds, please email support@fluidretail.com and provide a URL to each feed.

Manual Display Production

The manual display production allows for maximum flexibility and is typically used for entering smaller product catalogs and editing larger ones.

Add New Product

Click Add New Product in the upper right. Enter product name and product ID. The product ID should match the value you use in your e-commerce catalog.

Add and configure Variations

Each product must contain at least one variation. If your product has multiple colors, you will create a separate product variation for each.

Enter Variation Name and Inventory ID - The "variation name" will be displayed when users mouse over a color swatch ("Sky Blue"). The "inventory ID" is usually a color code, for ex: "BLUE". This value is important to allow the display to communicate with other HTML elements on the page like a combo box which displays color. If your product does not have multiple colors set the variation name and inventory ID to something generic like "default".

Next, configure the variation:

1. Upload product image – Click "Upload Images". You will be given the option to upload Static or Configurable Images. Choose "Static Images."

Note: Configurable images allow you to upload a single gray-scale image and tint it using the authoring tool to produce images for all product colors. To learn more about this feature, see the Fluid Display Configurable Images Guide)

Once your image is uploaded, the authoring tool will render a preview. If you intend to feature multiple views of your product and/or 360 rotation, upload additional images and enter a View Name for each. Otherwise, View Name can be left blank.

2. Configure swatch – If your product has multiple variations, specify a swatch to allow users to navigate among them. A swatch can either be a solid color value or an image. To set the swatch to a color value, click the "RGB Swatch Values" tab and specify one or more colors. If you wish to use an image, you can either set the "Type" of the main image to "Both" so that it will be used as both the main image and the thumbnail, or upload a new image and set the "Type" to "Thumb". Save Variation.

3. Repeat the above process for each color variation

When complete, you can preview your variations in the main product grid by selecting them in the right-hand pane. A drawer will slide out showing a preview of each variation. If your product has multiple variations, ensure that each variation has a default swatch and main image before moving on to display creation.

Creating interactive merchandising displays

Once you've uploaded product data and images and set a display profile for each product, you're ready to begin building displays.

Select Products – To help select those products which need displays, Fluid Retail tracks which products have been modified since the last batch creation process using the Display Status Field:

1. Using the search pull-down, select "Display Status".
2. Next, choose "Not Up-to-Date" and click "Find." This will show all products which have been affected by the batch import process.
3. Click "Select All" in the lower left.

Alternatively, you may manually choose a few products or the entire catalog.

Create Displays

1. Click "Create Displays for Selected" at the bottom.
2. Next, choose "Use Display Profiles".

The system will batch create displays for all products selected using their respective Display Profiles. This process will overwrite all existing displays. If you choose to log out of the tool, you may check the status of your batch by clicking Administration > Job Status panel.

Deploying displays to your site.

Configuring the System for Display Deployment

Displays can be deployed in two ways:

Download: Displays can be downloaded locally as a .zip file and then pushed to the server where they will be hosted. Just select the displays you want to download and click "Download Selected".

TIP: For initial download, be sure to check the download "Fluid Retail Core Components" checkbox. See the next section for complete details on file types.

Your browser will allow you to save the displays locally. There is no additional configuration necessary to use this functionality.

Deploy (preferred): By default, displays will be deployed to Fluid Display’s hosting environment when "Deploy Displays" is clicked. If you wish to host on our servers, additional hosting fees will apply.

Alternatively, the user can deploy assets using one of four methods:

• FTP
• SFTP
• WebDav
• RSync

Deploy Targets are used to configure and store these deployment locations. Go to Admin > Deploy Targets.

FTP/SFTP/WebDav

Enter a name for the deploy target, target server URL (e.g. www.mysite.com), transfer method (FTP, SFTP or WebDav), target directory, username and password. Note that the target directory should be relative to the home directory of the FTP or WebDav account. The home directory is the default directory when logging in using your credentials. The username and password must have permissions to add and delete both files and subdirectories.

RSync

Configuring an RSync deployment target is similar but target directory is replaced with Rsync module name.

Instructions for configuring the RSync server itself is as follows:

1. Given a standard server such as Red Hat Enterprise, install the packages "rsync" and "xinetd" if not already installed.

1. Craft a file rsyncd.conf based on this template to match the needs of your server. Copy this file to /etc/rsyncd.conf, chmod 0644 & chown root:root.
2. Set the username/password in rsyncd.secrets as shown in this template which matches the rsyncd.conf file created above. Copy this file to /etc/rsyncd.secrets, chmod 0600 & chown root:root.
3. Edit the file /etc/xinetd.d/rsync and change the line which says "disable = yes" to "disable = no" and save.
4. (Re)start xinetd with the command: /etc/init.d/xinetd restart
5. Enable xinetd on startup with the command: chkconfig xinetd on

NOTE: If your server is behind a firewall, you will need to modify its settings to accept connections from fluidretail.net, IP 208.75.210.72

Deploying Displays

First, select the products you wish to deploy. Either manually select some displays or use the search box to find where "Deploy Status" does not equal "Update to Date". Next, click "Deploy Selected" and the system will prompt you to select a deployment target:

Select your configured deploy target. You can deploy or download three types of assets:

• Fluid Displays – dynamic, interactive displays

• Static Images – static images created using Create Static Images, Image Profiles or Display Profiles.

• Fluid Retail Core Components - If this is your initial deployment to this server, you have added a new custom template or you have been notified of a new release of Fluid Retail since your last deployment, check this checkbox. Fluid Retail core components are Flash, JavaScript and XML files required for Fluid Retail to work properly. This box should be unchecked during the regular publishing process of deploying new products using existing templates.

When you click "Deploy" the system will establish a connection with your server and transfer files. Any older files will be overwritten.

Once files are transferred successfully, the system will confirm that the deploy process have successfully completed.

Note: It is not necessary to remained logged into the Fluid Retail system for the deploy process to complete. At any point you can log into the system and check Job Status in the Admin tab.

Next: Embedding and integrating components in HTML