NOTE: This describes schema version 1.7.
A product has codes, texts and pictures. The texts and pictures can be defined for multiple languages. For each product a set of complement products can also be defined.
Note that all used languageCodes must be registered on the account used to upload the information to Mediablob. Please check your account details with your Shoppa representative if you are unsure.
Lets build a product from scratch and see how different requiements evolve its xml definition.
Lets say our customerId is 1143 and we have a product with only some basic information:
brand: Orrefors
name: Champagneglas
sku: 65467-14
ean code: 123456789012
This corresponding xml format is:
A product must always have at least one text section. Brand and name are required for new products. In the example above the product is described in the Swedish language.
We extend the product with additional sales arguments and a unit for prices:
short sales argument: Exklusivt tvåpack. En perfekt bröllopspresent.
long sales argument: Efva Attling är en juveldesigner som har använt sin rika erfarenhet och expertis för att skapa glaskonst. Hennes tredje glas är ett maskulint martiniglas med en silverring.
unit: st
The xml for describing the product now becomes:
To protect content against xml formatting constraints, the & character is xml encoded. This follows the xml specification and must be used for any content.
We decide to support English too. The xml gets extended with an additional <text /> section. We also start the product with a generic language text xx with generic text for all languages unless overridden.
Even without actual such texts, we recommend always including a row for xx to prevent duplicate products in the future.
Finally, we add pictures to the swedish brand and productName fields. English users do not get to see any pictures for now.
As you can see, the pictures are referenced by a hashCode. What hashCode to use will be described in detail in the Pictures section.
Pictures require a countryCode. This is a legacy construct and is easily created by lowercasing the last two characters of the languageCode.
The hashCode returned from the picture uploader is based on md5, but formatted as a guid. The difference is big or little endianess. If you prefer to reference the picture by its md5 code, you can use the md5 attribute instead:
Instead of referencing an image by hashCode or md5, you can provide a public uri from where Mediablob can download the picture for you. Mediablob will only use the same uri once, so you must ensure the uri is unique for each picture. Avoid using this scheme unless you are using a picture database that ensure unique uri's per picture.
In the sample above, Mediblob would keep using the original downloaded picture even if the content of the uri changes.
Sometimes you need to delete existing products or parts of a product, or you want to make sure any existing information is removed and not merged with the new information. Below we describe the different approaches you can use to solve this.
You delete a product field by simply assigning it as an empty field.
Lets say we want to delete the infoshort field we added in Adding a new text field. We can do that by sending the following xml:
Note however that in case this product was overloaded from another customer node, the original text will now be visible again. If you actually want the field to be empty, regardless of what has been defined at a higher level, you need to write an empty space to the field, like this:
The space inside the field content is mandatory here. If the field is empty the original content will be visible again.
To remove an entire language from our example product, we add a <text/> section with the attribute delete="true":
There is no reason to add text fields to a deleted <text /> section since the import will simply ignore them.
If you want to replace all texts for a specific language and make sure there are no legacy fields left behind, you need to write a delete-section followed by the new <text /> section:
Make sure the delete comes first, or your newly added texts will be deleted too!
Sometimes you want to delete an entire product, with all texts, codes and picture references. This is done with the following xml:
As before, if the product is owned by another customer, the product will still be visible with its original content.
When you want to extend a product with additional information you simply send the product information you have with an existing product identifier.
The extended information can be anything; an additional language, an extra product code or picture references.
You can also reference the product by its ean code instead, by replacing the first line with <product id="123456789012" idType="EAN13">. As you see, any code can be used as long as it is unique to the product.
Continuing on the section Extending product information, English could have been added to the existing product by sending only this xml:
As you see, adding a field or an entire extra language is essentially the same. Just reference the product by its identifier and add the missing information.
As stated initially, all products at a top customer node are available to all children. This means there is usually no need to add products at a store level. Instead the products are added to the HQ node or any branch-nodes in between HQ and the stores used for segmentation of information.
In some instances a store or branch-node needs to replace a certain part of a product. This is achieved by sending the same kind of update mentioned above, but for another customerId. Customer id´s are defined in the SOAP metadata and described in detain in a later chapter.