Importing products from a XML file

CCIDESQ features a product importer that can read data from an XML file organized in a specific way. You can use any tools to generate the XML file, and CCIDESQ will import it and add the items found in the database, or update existing ones.

The structure of the file

The structure of the XML file so far can be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<cci:Catalog TotalProducts="142675" xmlns:cci="http://cci.ca/">
<cci:product>
    <cci:P_Author>Product contributor name</cci:P_Author>
    <cci:P_ISBN>ISBNCODE</cci:P_ISBN>
    
<cci:P_ISBN>ISBNCODE</cci:P_ISBN>
    <cci:P_InternalCode>INTERNALCODE</cci:P_InternalCode>
    <cci:P_EAN>EANCODE</cci:P_EAN>
    
<cci:P_Title>Product title</cci:P_Title>
    <cci:P_OriginalTitle>Original title</cci:P_OriginalTitle>
    <cci:P_Price1>0.00</cci:P_Price1>
    <cci:P_VatPercentage>19.00</cci:P_VatPercentage>
    <cci:P_PublisherRRP>0.00</cci:P_PublisherRRP>
    <cci:Category>Category name/Subcategory/Sub-sub category</cci:Category>
    
<cci:BM_Category>BookManager category name</cci:BM_Category>
    <cci:P_StockCount>0</cci:P_StockCount>
    <cci:P_Description>Description</cci:P_Description>
    <cci:P_TeaserDescription>Teaser/short description</cci:P_TeaserDescription>
    <cci:P_Weight>0.0</cci:P_Weight>
    <cci:P_Height>0.0</cci:P_Height>
    <cci:P_Width>0.0</cci:P_Width>
    <cci:P_Depth>0.0</cci:P_Depth>
    <cci:P_Published>0</cci:P_Published>
    <cci:P_ShowOnSite>0</cci:P_ShowOnSite>
    <cci:P_AudioTrackListing/>
    <cci:P_ImageName>filename.jpg</cci:P_ImageName>
    <cci:P_SupplierCode>SCODE</cci:P_SupplierCode>
    <cci:P_Supplier>Supplier name</cci:P_Supplier>
    <cci:P_Producer>Producer name</cci:P_Producer>
    <cci:ProducerStatus>Available</cci:ProducerStatus>
    <cci:ProducerStatusAllowOrdering>1</cci:ProducerStatusAllowOrdering>
    <cci:ProducerStatusDisplayStatus>1</cci:ProducerStatusDisplayStatus>
    <cci:ProducerStatusDisplayProduct>1</cci:ProducerStatusDisplayProduct>
    <cci:P_ShelfLocation>48D3</cci:P_ShelfLocation>
    <cci:P_CarobId>1234</cci:P_CarobId>
    <cci:P_Subtitle>The Subtitle of the Product</cci:P_Subtitle>
    <cci:P_NumberOfPages>124</cci:P_NumberOfPages>

    <cci:P_DateAdded>2017-02-13T12:23:00</cci:P_DateAdded>
    <cci:P_ReleaseDate>2015-06-20T01:02:00</cci:P_ReleaseDate>
</cci:product>

The fields in the XML are named after the names of the product fields explained in the product fields explanation page.

The fields

TotalProducts="xxxxx": Specify the number of total items there, to enable progress indicator during the import process. If this number is not specified, the system cannot detect from the XML file (which is imported using a stream), the total number of items, so progress will not be indicated.

P_Author The name of the contributor for that particular product. If the contributor is not found in the database, a new one is created with this name and assigned to the product. This new contributor is PUBLIC by default.
P_EAN The EAN code for the product.
P_ISBN The ISBN code of the product. It is not important whether it is an ISBN 10 or ISBN 13.
P_InternalCode The Internal Code of the product, as you define it yourself.
P_Title Product title
P_Subtitle The subtitle of the product. Sometimes products can have a subtitle, in addition to the main title. This is stored separately in CCIDESQ
P_OriginalTitle The original title of the product, if it is a translation
P_Price1 The main price of the product
P_StockCount The total amount in stock at the moment. Must be an integer. E.g. 5
P_VatPercentage The VAT percentage associated with P_Price1
P_PublisherRRP the publisher's Recommended Retail Price for the product
P_Description Product description. If your descriptions contain HTML tags, such as <p>, <br />, etc., you must either encode them with XML-friendly characters: &lt;p&gt; or wrap the description in a CDATA.
P_TeaserDescription A short version of the description, usually a phrase or two, as a teaser.
P_Category The name of the category the product will be assigned to. While importing, the category is automatically added under the 'main products node' specified in the settings. Then the product is automatically added to this category. Separate multiple-level categories with a slash (/) and they will be created in that hierarchy: Node/SubNode/Sub-Sub node and the product will be allocated to the deepest level (leaf node)
BM_Category If you are importing a list of products from BookManager, the field for the BM category can be provided here for reference purposes.
P_BM_ImageFile The name of an image file (or a URL) if the image is to be updated and loaded from the image files directory (or downloaded from the URL if it is a URL). The image download happens using a Worqer task in the background after the import of the XML file finishes.
P_Weight, P_Width, P_Height, P_Depth Product dimensions and weight, specified in decimal format
P_Published Whether to make this product public or not, on the website. Must be 1 or 0.
P_ShowOnSite needs to also be specified as 1 if the product is to appear on the website. In combination with P_Published.
P_ImageName the filename of the image of the product, if existent. The system will find it in the specified folder and import it. JPG only.
P_AudioTrackListing If the product is a music album and the names of the audio tracks are available, store them here.
P_SupplierCode The code that a supplier has given to this product if different from ISBN, EAN, etc.
P_Supplier The name of the supplier of the product.
ProducerStatus The status of this product with its original producer/publisher. This indicates if the original manufacturer of the product has the product in stock, or what is the current status. For example the following values could be used: Available, Out of stock, Temporarily out of stock, etc. There are no constraints as to the names or values specified here.
ProducerStatusCode If the local database contains a specific code (number) referring to the ProducerStatus, it can be added here. For example: 1 - Available, 2 - Out of stock, 3 - Currently reprinting, 4 - Out of print, etc...
ProducerStatusAllowOrdering This field specifies whether the product with this producer status code can be ordered online. Possible values are 0 or 1. 0 - do not allow ordering; 1 - allow ordering. Updates the product field 'P_ProducerStatusAllowOrdering'
ProducerStatusDisplayStatus This indicates whether the producer status will be specified/displayed on the public website or catalogs or lists. For example if an item is "Out of print" but you still want to display the product on the website but inform your customers that the product cannot be procured anymore, allow displaying of the status online. Updates product field 'P_ProducerStatusDisplayStatus'
ProducerStatusDisplayProduct This indicates whether products with this producer status are displayed on the website at all. This works in combination with P_PublishedP_ShowOnWebsite fields in the database. A value of 1 means "display product", and 0 means "do not display product". If the product has ProducerStatusDisplayProduct = 0 but it has P_Published = 1 and P_ShowOnSite = 1 - the product will NOT be displayed. These fields work in combination. Updates product field 'P_ProducerStatusDisplayProduct'
P_ShelfLocation A string with a code specifying the location of the product in the store shelf/warehouse so that the product would be easily tracked when processing orders and picking items. If this field has a value, it is being included in the cofirmation e-mails to the owners of the website to help with order picking, as well as in the CCIDESQ administration interface when displaying the order and product details. Updates the product field 'P_ShelfLocation'
P_NumberOfPages The number of pages in a book. Must be an integer, e.g. 124
P_CarobId The code/unique id/primary key for the product in the Carob database. Currently Carob is used in the UK for wholesale operations. Updates the product field 'P_CarobPrimaryKey'
P_DateAdded The date when the product was added to the database. This is not the release date (see below). This field is normally added automatically by CCIDESQ when you add a new product and it is usually the date and time of that moment. But this field also controls the ORDER in which products are displayed on the public site (latest first), so if you change it, it may happen that some old products appear as 'new'. This is the date and time that is used when the customers select on the public site the sort 'Latest first' or 'Newest first' or 'Most recent'. Products in CCIDESQ are also shown, using this field, in the order they were added. The structure of the field should be: 'YYYY-MM-DDTHH:mm:ss' (notice the 'T' between the Date and the Time components. The format for this DateTime is in ISO 8601.
P_ReleaseDate The date when the product was released to the public or published by its producer. The format for this date should be the same as the P_DateAdded (ISO 8601). If you don't know the time, just use 'T00:00:00' for midnight.

 

A few notes about the file format and fields when producing the file:

It is obvious that not all fields will be applicable to all websites or databases. When you do not have values for a particular field, or a value is not present at the time of the file export, you can choose to do one of two things:

a. Not include the field at all. This means, if you do not have P_CarobId for example, simply do not output the tag in the XML file. This is the recommended method as it also keeps the file size down.

b. Include the field as an EMPTY XML field. Please take note that EMPTY fields and VALUELESS fields are two different things. A field with no value is represented as follows: <Field></Field>. An EMPTY field is represented as follows: <Field /> . Do NOT include valueless fields if you don't have a value at the time of file generation or a value is not usually provided by your export program.

Since the file can be very large, and supports tens of thousands of products, it must reside on the server at the moment it is imported. That is why, means of uploading the file are not treated in this document.

Importing the file

The importer will create a task via the web service for CCIDESQ and process the import sequentially, in the background. This means that you can start the import, and close your browser. The import will happen on the server and you can check the progress using the Long-running tasks page found in the 'Manage' menu in CCIDESQ.

To start importing products, go to the Products page. At the top there is a link called "Import from XML". Click this link to submit an import task for the system. Then you can proceed to the long-running tasks page to check on the status.

Products in the XML file that have a blank ISBN code will be ignored.

You can also upload XML files in CCIDESQ now and process each one manually, instead of just one file from one fixed location.

Images

If there are images available in a designated folder, the system will try to find those images and add them to the imported/updated products. Alternatively you may specify a URL for the product images in the ImageName field and the image will be downloaded from the remote server, however this will cause the import process to go much slower.

If the products are updated, not added for the first time, and they do have an image, the image will be replaced. While adding or replacing images, the system will automatically create resized versions of the images, for various purposes.