Future price changes requires the use of StoreInfo schema version 1.6 or higher and is only supported by Shoppa versions 2.25 or higher.

Changing the price for a later date

Assume we have the following base price list to begin with. It has a start date of 2020-01-01

From 2020-01-15 we want to increase the price of product 111111 to 59.95 SEK. We also want to lower the price of 222222 to 19.95 and 444444 to 69.95 two weeks later.

Here we have to refer to the same package ID as the base price list if the changes are to be combined with the base price list at desired change date. Each package startdate in the XML defines when the changes will apply.

We have therefore created one package with startdate 2020-01-15 and one with startdate 2020-02-01 for the respective price changes.

The price of the product 333333remains the same at each change date.

Periodically changed price

If we want to reduce a price during a short period of time, for e.g. under a two month time. Afterwards we are to set the old price back again. We can not set a stopdate for the reduced price, instead we have to send the higher price on new.

The product will now be on a reduced priced during the two months between 2020-02-01 and 2020-03-31. At 2020-04-01 th eproduct will return to its original price.

Deleting future price changes

It is possible to remove a previously uploaded package in case it was incorrect. This will remove all price changes that were set to occur at the specific date.

We delete the price changes above for 2020-02-01 with this xml:

The price change at 2020-01-15 will still be in effect.

To remove individual products from future price changes, use the delete attribute on the product element, like so:

We have now deleted the change for product 444444.The change for product 222222 at 2020-02-01 will still remain.

Removing all future price changes for a product

Here we will send in a few price changes for the product 111111 over a period of time. We will have price changes at each package startdate.

To remove all future price changes for product 111111we have to delete the product from each future price change package with the same startdate defined as when the change were to occur. The XML will look like this:

Assuming we don't know when all the price changes for a product occurs, we can delete all prices for a product by sending in the product with an empty price value. The startdate of the package will determine from which date the prices are deleted.

All future price changes and the current price for product 111111 are now deleted, starting 2020-01-15.

Correct a future price change

Here we have a price change for 2020-02-01. After a while it is decided that the product should have another price from the same startdate. Correcting the price change is accomplished by setting the new price for the same startdate.

At 2020-02-01 the product will now have a price of 24.95 instead of the original 19.95.

Replacing an entire pricelist

Some time passes and we have made multiple changes to our pricelists at different times. For some reason we may have the need to replace all prices in a pricelist with new prices. Some products may no longer be relevant for example. We do this by setting the fullPackage attribute like this:

Now there will no longer be a price for product 333333 or 444444 starting from 2020-04-15.

/api/xml

Used for uploading Shoppa XML's to the integration service bus queue

PUT https://api.mediablob.com/api/xml

Available Shoppa XML's can be found at

Headers

Request Body

Used for uploading a custom XML to the integration service

PUT https://api.mediablob.com/api/xml/custom

Custom XML's will be passed through one or several XSLT schemas before being uploaded to the service bus queue. XSLTs are uploaded by Shoppa. To upload or change an XSLT, contact your Shoppa representative for help.

Headers

Request Body

Operation to list all uploaded XML's for the defined date

GET https://api.mediablob.com/api/xml/{date}

Headers

/api/auth

Validate authentication and fetch environment information

GET https://api.mediablob.com/api/auth/me

Can be used to fetch information about the environment node structure. Such as customerIds, available languageCodes/countryCodes.

/api/status

Operation to check if the XML processing is done

GET https://api.mediablob.com/api/status/{sessionId}/done

{sessionId} corresponds to the hashcode returned by a 202 Accepted response in

Operation to get a detailed information about the XML process

GET https://api.mediablob.com/api/status/{sessionId}/result

{sessionId} corresponds to the hashcode returned by a 202 Accepted response in

/api/images

Upload images

POST https://api.mediablob.com/api/images

Upload one or more images to Mediablob as multipart form data objects. If this image already exists, the In C# you need to add the images to a MultipartFormDataContent object, which you add to an HttpClient call. The response contains the Mediablob id for each image, which you can use to reference the images in further integrations. If your image has a clipping path you can add these parameters to the call to tell our rest endpoint which clipping path you want to use. The invert parameter is there to make it possible to invert the clipping path.

Query Parameters

Headers

Request Body

Check if an image exists

HEAD https://api.mediablob.com/api/images/{Mediablob-hashcode}

Verify that an image exists in Mediablob by using the Mediablob-hashcode that was returned when the image was originally uploaded.

Headers

Find the Mediablob hashcode for an uploaded image

GET https://api.mediablob.com/api/images

Find the Mediablob-hashcode for an image that has been previously uploaded. You need to provide one of md5 or uri query parameter, but not both in the request. The Mediablob-hashcode is returned in the response if it is successful, which you can use to reference the image in further integrations.

Query Parameters

Headers

Integration user

Legacy

While our SOAP based webservice will remain in operation for some time longer, it is no longer being maintained and will not be updated with bug fixes, etc. If you are already using the SOAP based service we recommend that you switch over to using our REST based service at your earliest convenience. If you are integrating your system to ours for the first time, we strongly urge you to use the REST based service, not the SOAP based one.

The SOAP specific documentation will remain online as long as we accept SOAP requests, only as a convenience to our customers currently using it. Again, if you are building a new integration, use REST instead.

SOAP

Soap is a standard protocol that will not be discussed in detail here. There are some peculiarities to know about when integrating with Mediablob though; specifically Mediablobs use of an <AuthHeader /> section.

Another quirk, that is handled automatically by tools such as Visual Studio, is that xml content must be xml-encoded.

The AuthHeader

Mediablob does not use any cookies or other common login mechanisms to validate access. Instead Mediablob expects an AuthHeader section in the soap header.

The AuthHeader looks like this:

The username and password authenticates the user. Mediablob then verifies the users privileges and authorizes the rest of the request.

The customerId is used to instruct Mediablob which customer node the uploaded xml file relates to. The customerId can either be a ShoppaID assigned by Shoppa when the customer node was created, or an ExternalID assigned to each store by the customer.

Contact Shoppa Service Center to change what ExternalID to use for different stores.

The customerId must always be for or below the node the user logs in to. To prevent pre-generated xml-files to be uploaded to the wrong account by mistake, the customerId must correspond with the customerId of the uploaded xml file.

Encoding

The content of any xml element must be xml encoded. This is achieved by replacing each character with its encoded counterpart. Thus, in the Mediablob product xml you would need to encode the product text Köp & vinn! as Köp & vinn!.

Xml encoding is automatically handled by high-level frameworks like C# and Java. You only need think about this when you create your xml file manually.

What can be a bit confusing is when you wrap the Mediablob xml in soap. Since your xml file is content in a soap element, it needs to be xml encoded, including any text you encoded inside your xml. The product text above would then become Köp & vinn!.

Mediablob also requires an xml declaration line at the top.

Example SOAP Request

Lets say we want to upload the following product definition:

Using the following user details:

• username: demouser1

• password: Not_a_real_password

• ShoppaID: 1143

Encoded and wrapped in a valid soap request this becomes:

Copy this text and POST it with Wizdler to Mediablobs development endpoint. You should get the following response with status code 200 if you did it right:

Mediablob API is the developer interface for storing product information in the Shoppa eco-system.

The api comes in several versions. All api versions are both forward and backwards compatible with any version of the Shoppa Client, but to take full advantage of the latest functionality of Shoppa Client, your Mediablob integration must use the latest api version.

All xml schema definitions (xsd) can be downloaded at XSD

The customer node

An integral part of the Shoppa eco-system is the customer tree. All users belong to a customer node, which in turn has a parent node. All customer nodes for a tree in this way, with one parent and optionally multiple children.

The customer tree is created by Shoppas specialists together with the customer. Contact Shoppa Support Centre if you need to update the customer tree.

Any product or storeinfo-object created at a node is available to all lower levels, provided it is not restriced by country code.

A customer can also get access to content from an external customer node if a reference is created to that node. This is used for instance to provide supplier information to several different companies. Customer references can only be created and removed by Shoppas solution architects.

The Product object

All information in Mediablob is based around a product. Products support different languages and can be restricted to a specific country.

A product has several named text fields. Allowed field names are defined in the and are used by Tags in Shoppa templates to display the correct product information.

At a customer level, the product stores up to one text and one image per field and language code.

The same picture can be assigned to several fields and different pictures can be assigned to the same field, but for different language codes. This is especially useful for images with embedded texts.

Products can be partially overridden at any customer level. This information is then used for all customer node further down the tree. If an overriden text is later deleted, the original text is restored.

The Product primarily stores static information that is not bound by time. When a product is updated the change is visible immediately to all users and remains the same until the product is changed again. Thus, products shall not contain volatile information such as price. Such properties should be handled by StoreInfo objects.

The StoreInfo object

Existing products can be enriched for specific customers and timespans.

While any text or picture of a product can be overridden, StoreInfo objects typically describe pricelists or campaigns. StoreInfo is perfect for tracking different product prices per store.

It is important to create the products before relating to them in StoreInfo objects.

The Mediablob API 1.0 is based on xml.

While the original transport was only over SOAP, Mediablob now supports async posting of xml files over https. This method is much easier to use, and returns control faster to your application.

While there are no immediate plans to remove the legacy soap support, the async https transport is highly recommended for new api development.

HTTPS endpoints

There are two available endpoints; one for development and testing, and the other for production use.

1. Development: https://api.test2.mediablob.com/api/xml

2. Production: https://api.mediablob.com/api/xml

REST/HTTP Developer tools

Since the api supports standard http requests, it is easy to connect any environment to the api once you have your account details.

An effective way of testing the Mediablob integration is by using Chrome with the extension .

1. Install the addon.

2. Open the new app from the upper right corner of Chrome.

3. Select the Method, i.e. PUT and fill in the url to the endpoint

   .

Shoppa also provides C# source code for a sample application that uploads xml files to the api.

Legacy SOAP endpoints

There are two available endpoints; one for development and testing, and the other for production use.

1. Development: http://ws.test2.mediablob.com/services/products.asmx

2. Production: http://ws.mediablob.com/services/products.asmx

You can open the endpoint urls in a standard browser and read about the provided functions.

SOAP Developer tools

Since the api supports standard soap requests, it is easy to connect any environment to the api once you have your account details.

An effective way of testing the Mediablob integration is by using Chrome with the extension .

1. Install the addon.

2. Browse to the wsdl-definition of the webserver at .

3. Click on the Wizdler icon in the addons toolbar and select the function you want to call.

4. Rewrite the example content in the browser window.

Shoppa also provides C# source code for a sample application that uploads xml files to the api.

How to use the endpoints properly

Use the development endpoint for development and integration testing. The test environments have additional data format validation that gives better developer feedback. By working in a testing sandbox, you ensure any errors can be detected without affecting production users.

Switch to the production endpoint when uploaded data shall be seen by the end users.

The environments can of course be used in parallel. Just understand that testing and production environments are completely separated.

Requesting user access

You will need a username and password to access any services in the Mediablob api. You also need to know your customer id(s) for many operations.

Accounts to the test and production environments are provided by the Shoppa Support Centre. Ask your Shoppa representative to request an account on your behalf.

As stated before, any product field can have one picture assigned to it. The same picture can be referenced by many fields, and many products, in several languages.

Pictures are uploaded to Mediablob by calling UploadImage2 or UploadAndClipImage. When an image is uploaded, its md5 hashCode is returned. Use this hashCode as future reference in products.

To reduce bandwidth usage, api users are encouraged to calculate the md5 hash code themselves and check if the image exists in Mediablob through the ImageExists or ImageExistsMd5 functions prior to uploading images.

Note: Images are always hashed before being processed by Mediablob services, so it can be correctly precalculated before uploading.

Note: It is not possible to delete images in Mediablob through the API.

UploadImage

Products have a number of fields in which you can enter information about the product. This document provides a short summary of the fields common to all users. New, specialized, fields can be created on a customer basis, contact your Shoppa representative for more information.

Required fields

When creating a new product, there are certain fields that must be defined:

• Brand

• Product name

• At least one Code field (see below)

Code fields

Code fields are special, in that their values must be unique. That is, no two of your products may contain the same value in, for example, their Code 1 field. The uniqueness constraint does not carry over multiple fields, e.g. one products Code 1 can be the same as another products Code 3 without issue. The constraint also doesn't carry over between customers, i.e. one of your products may have the same Code 1 as a product belonging to another customer.

Text fields

Price fields

Price fields are only available in price lists and campaigns. They can therefore only be integrated using the storeinformation XML.

Picture fields

Pictures can be attached to any fields, but we do have some recommendations, i.e. the main product picture should go in the 'product name' field. These recommendations are listed below.

• Primary image - productname

• Secondary image - techname

• Third image - infoshort

Additional fields

There are additional fields with no intended use case. These can be used if there are no other suiting fields available.

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.

A basic product

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.

Extending the product information

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.

Additional languages

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.

Picture support

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.

Reference a picture by its md5 hash

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:

Reference a picture with a public uri

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.

For every product we can assign a list of complement products. The complements are displayed in Shoppa when the base product is displayed and can be automatically assigned to templates to easily build multi-product signs.

Note: Just because product A assigns product B as a complement does not mean the opposite is true. You must explicitly assign all relationships you want to use.

Adding two complement products

Lets assign a complement product to our sample product:

<mediablob customerID="1143" customerIDType="ShoppaID" createDate="2018-05-12T00:00:00" schemaVersion="1.7" xmlns="http://shoppa.com/mediablobSchema">
  <products>
    <product id="65467-14" idType="Code1">
      <complementProducts>
        <complementProduct id="65468-1" idType="Code1" />
        <complementProduct id="65468-3" idType="Code1" />
      </complementProducts>
    </product>
  </products>
</mediablob>

You can of course assign complement products at the same time you create your product or modify other properties of it. The only requirement is that the complement product already exists in Mediablob.

Replacing existing complements

If you send a <complementProducts /> list as above, the new complements will be merged with any existing complements and make the list of complements longer. If you instead want to replace the existing complements with a new list, you need to set replace="true":

The above xml effectively deletes complement 65468-3, since it is no longer part of the list.

Deleting all complements for a product

If you want to delete all existing complements for a product, you set delete="true" on the <complementProducts /> section:

Note that deleting the complements list does not delete the product itself.

Local prices in combination with central prices requires the use of Shoppa version 2.25 or higher.

Pricelists on a store level overrides central prices only if the store is subscribed to the central pricelist, both pricelists have the same package ID, and the local pricelist does not have the name "STANDARD"

All future price change functionality is applicable for local overridden pricelists as well as central pricelists.

Locally overridden prices for a product will always trumf any centrally price changes for the same product.

Local override of central pricelist

Here we have a central pricelist stored on a HQ level.

In one of the stores we have different prices for the products with ID 222222 and 333333. We will therefore only send the price changes to the local pricelist.

Store1 will now have the local prices in addition to central prices that are not overridden. The other stores will receive all the prices from the Central Pricelist.

Deleting local price overrides

If a local price stops being active and we want the central price to be used again, it can be accomplished by deleting the local price from its pricelist.

Here we have deleted the product with ID 222222 from the local pricelist. Store1 will now receive a price for the product from the Central Pricelist. Other local price overrides will still remain.

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.

Adding a new text field

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.

This describes .

Product groups is used for creating a hierarchy of products. It makes it easier for the users to do the search by brand or by product type. Much like pricelists, product groups are not inherited along the customer tree automatically, only stores that subscribe to the the product groups can see them.

Usage

Campaigns

Campaigns describe temporary prices used at one or more stores for a specific time period. Campaigns are usually used to show customers the original price and how much they save during the campaign. For this reason, campaigns are layered on top of the stores pricelist when used by Shoppa.

Like pricelists, campaigns are described in a StoreInformation package. Campaigns are always created with a start- and a stopdate and they always need a name that can be used in Shoppa Client to select it.

As with pricelists, campaigns can be identified with name, startDate and countryCode, but for simplicity we recommend using a reliable id instead.

A campaign can not be converted to a pricelist and vice versa. If you create the wrong kind of package you need to delete the package and create a new one from scratch.

A basic campaign

Lets make a 50% off campaign for our sample glass 65467-14 from October 1st - 4th. The xml for this is:

Changing the duration

We decide to postpone our campaign one day and extend it to a full week. If we simply set a new startDate we would update product prices at that date rather than of changing the startdate of the entire campaign. Moving the campaign thus requires us to use the attribute newStartDate:

Campaign visibility

What campaigns to run in an organization may be known a long time at HQ, but it may be sensitive to tell the stores too early and risk informing customers and competitors. By setting the visibleStartDate attribute you decide how long beforehand the stores see the campaign. All users at HQ still see the campaign in their clients and can validate its content.

Similarly, some stores may want access to campaigns after they formally end, to run them a little longer and get rid of excess stock. To keep the campaign visible in Shoppa Client after the campaign ends you set the visibleStopDate attribute.

Complement products

A product can have complement products assigned to it specifically in a campaign. You can also assign campaign information to the complement products as you are assigning them. Note that values cannot be set with the value attribute, they have to be contained by the field element.

You should also add the attribute complementBehaviour to the product element. This takes one of three values and determines the way complement products are added and/or removed. The accepted values are replace, delete and merge. They do the following:

• Replace: Removes all existing complement products and replaces them with the new ones. This is the default option.

• Delete: Removes all existing complement products. Any new complement products will be ignored.

• Merge: Adds the new complement products to the set of existing ones.

Deleting a campaign

If a campaign should be removed completely, that can be achieved by setting the delete attribute in the package tag. We refer to the campaign by defining the corresponding id, startDate, and stopDate. The xml for this is simply:

Removing a product from the campaign

If we instead only want to remove a selection of products from the campaign, we set the delete attribute in the product tag. The xml for this is simply:

Supported image formats

BMP (.bmp)

RGB – Indexed and 8 bits (per channel).

GIF (.gif )

Supports transparency RGB – Indexed

JPEG (.jpg and .jpeg)

RGB / CMYK / Grayscale Recommended format for product images that don’t need transparency and other photos.

PNG (.png)

RGB – Indexed, 8 bits and 16 bits (per channel) Grayscale – 8 bits and 16 bits (per channel)

Recommended format for graphics, logotypes and product images that need transparency.

TIFF (.tif and .tiff)

RGB – 8 bits and 16 bits (per channel) , supports transparency CMYK – 8 bits (per channel).

WebP (.webp)

Recommended resolution

We recommend using at least 150 PPI for your images to ensure a good quality for printing. The area of the image box in Shoppa will determine what pixel dimensions are needed.

The Shoppa application can accept sign orders from external applications for printing. The sign order is an XML file which follows a predefined XML schema. The external application or PDA places the XML file in a predefined “hot folder” and Shoppa imports the file from this folder. The sign order can include one or many products. Each defined product can have text fields like name, brand, description, price and so on. The sign order has an auto print option. If this option is activated Shoppa will put all products on a predefined template and automatically send them for printing. When the auto print option is disabled Shoppa will show the products in a list for further action by user.

Requirements

A few things are needed in order to use the local integration functionality:

• The correct Add Ons for your enterprise and store level accounts. If you don't already have these, contact your Shoppa representative.

• The location of the hot folder needs to be specified in the Shoppa configuration file, see below.

• One or more display groups need to be created, preferably on an enterprise level account.

Hot folder

The location of the hot folder needs to be specified in Shoppas configuration file (shoppa2.exe.config). The relevant section is this:

If this setting does not already exist, add it in the <Shoppa.PL.Windows.Properties.Settings> section. If the folder does not already exist, the Shoppa client will create it on startup.

In order to send a signorder file to Shoppa, simply place it in the hotfolder, either by hand for testing purposes, or use another appliction.

The folder will contain three or four subfolders, depending on the version of the Shoppa client.

Archive

In Shoppa 2.25 and newer, finished files will be moved to the archive folder after three days. Older versions do not do this, and the archive folder is not created.

Error

If a something goes wrong when processing a signorder file it will be moved to the error folder, along with a .txt file containing an error message. A timestamp will be appended to the name of the signorder and the corresponding error file will have the same name, except for being a .txt file rather than an .xml file.

Finished

When a signorder is successfully processed it is moved to the finished folder. A timestamp will be appended to the name of the file.

Schemas

The Schemas folder contains a file called DisplayGroups.xml that describes the available .

Usage

There are several use cases for the signorder functionality. These are a few examples.

Printing from handheld devices

An application running on a handheld device can read the DisplayGroups.xml file if the hot folder is placed on a shared network drive and dynamically generate a list of available print options. The user can scan barcodes to select products and choose which template to use while out and about in the store. The application can generate a signorder and place it in the hot folder, and the selected signs will be printed through a computer running Shoppa. The user can then collect a stack of printed signs from the printer and start putting them up.

Generating product groups from another application

An application running on the same workstation as the Shoppa client can generate a list of products to print based on whatever business logic is available to it. The application can place a file in the hot folder and the user can access the list in Shoppa and create the required signs.

Uploading Images

Uploading images to Shoppa's central database can be done in two ways. Either the image is uploaded by itself or the image is uploaded with an URI in the Mediablob.xml.

Image compression

To optimize speed of the whole workflow from creating templates to printing in the stores, Shoppa automatically reduces image sizes if needed. Images larger than 2025 x 2025 pixels or 1 MB are compressed when imported to Shoppa's central database.

If the received XML-messages are malformed, or something goes wrong during processing of the message, an error message will be returned by our integration service. This document covers the most common error messages. Unexpected faults might produce unknown exceptions which are not covered by this document.

Error messages are reported in one of two ways: as XML or as plain strings. Problems with file contents are generally reported as XML, while other problems, such as authentication and connectivity issues are reported as strings. Error messages are contained in the <UploadProductXmlResult>-tag.

Example of XML-reported error; trying to add a product that does not exist to a campaign:

Example of string-reported error; wrong password was used:

XML-reported errors

The picture at '*' could not be retrieved.

The picture at the specified URL could not be retrieved. The reason is stated in the error text. Here are some example error texts:

• The picture at '*' could not be retrieved. Reason: The remote server returned an error: (404) Not Found.

• The picture at '*' could not be retrieved. Reason: Invalid URI: The format of the URI could not be determined.

• The picture at '*' could not be retrieved. Reason: Byte array for GUID must be exactly 16 bytes long.

• The picture at '*' could not be retrieved. Reason: Unable to read data from the transport connection: The connection was closed.

Recommended actions:

• The remote server returned an error: (404) Not Found.: Verify that the URL is working and is reachable by our service.

• Lost connection to MySQL server during query: Our service is not responding properly. Wait a few minutes and try again.

• Lost connection to backend server.: Our service is not responding properly. Wait a few minutes and try again.

Example XML excerpt:

The supplied picture hashcode does not match any known Mediablob picture

Error text: "The supplied picture hashcode (*) does not match any known Mediablob picture"

The hashcode doesn't match any picture in Mediablob.

Recommended action: Make sure the picture is uploaded before trying to assign it to a product.

Example XML excerpt:

Product does not exist in Mediablob

Error text: "Product does not exist in Mediablob"

You're trying to include a non-existing product in a campaign or price list.

Recommended action: Make sure the product is created before adding it to campaigns/price lists.

Example XML excerpt:

Product does not exist

Error text: "Product does not exist"

You’re trying to delete a product that does not exist, or add a product that does not exist to a product group.

Recommended actions:

• Deleting a product: The product is already deleted, or never existed. If possible, revise your integration system to avoid deleting already deleted products.

• Adding to product group: Make sure the product is created before adding it to product groups.

Example XML excerpt (campaign/price list):

Example XML excerpt (product group):

Product is a duplicate

Error text: "Product is a duplicate"

The product appears twice in a campaign or price list.

Recommended action: If possible, revise your integration system to avoid sending the same product twice or more in the same context (same campaign, product import, etc.).

Example XML excerpt:

Failed to Save the product

Error text: "Failed to Save the product"

The product could not be saved, probably because of something that happened serverside.

Recommended action: Wait a while and resend your data.

Example XML excerpt:

Found 2 products

Error text: "Found 2 products"

When trying to add a product to a product group, two products with the same code were found.

Recommended action: Resolve the conflict, or use a different code to add the product to the product group.

Example XML excerpt:

Product has duplicates in the Xml file. The first copy of the product is saved.

Error text: "Product has duplicates in the Xml file. The first copy of the product is saved."

The same product appears multiple times in a product import. Only the first appearance of the product is used, the other ones are discarded.

Recommended action: If possible, revise your integration system to avoid sending the same product twice or more in the same context (same campaign, product import, etc.).

Example XML excerpt:

The product already belongs to another supplier.

Error text: "The product already belongs to another supplier."

You are trying to modify, or superimpose a value on, a code on a product that does not belong to the customer node you are integrating to. E.g. a store cannot change a code on a product that is owned by their HQ.

Recommended action: If possible, revise your integration system to not attempt to modify codes on lower levels in the customer hierarchy than the product is created on.

Example XML excerpt:

Found existing product in database using the same product code

Error text: Found existing product in database using the same product code: CodeType '*', Value '*'. Product codes must be unique.

You are trying to assign a code to a product, but the code is already used on another product in Mediablob.

Recommended action: If possible, revise your integration system to avoid this behaviour.

Example XML excerpt:

Found duplicate code

Error text: Found duplicate code: CodeType '*', Value '*'. Product codes must be unique.

You are trying to assign the same code to multiple products within the same file.

Recommended action: If possible, revise your integration system to avoid this behaviour.

Example XML excerpt:

String-reported errors

User is not authenticated.

Error text: "User is not authenticated."

The authentication provided in the SOAP-object is not valid.

Recommended action: Verify that you are using the correct login information.

Either uri or keyword MUST be set on a product picture

Error text: "Either uri or keyword MUST be set on a product picture."

There is a picture tag that lacks 'uri', 'hashCode' and 'md5' attributes. One of them must be present to successfully reference a picture.

Recommended action: If possible, revise your integration system to avoid this behaviour.

Object reference not set to an instance of an object

Error text: "Object reference not set to an instance of an object."

The imported XML does not contain any information.

Example of imported XML:

Recommended action: If possible, revise your integration system to avoid sending anything if there is no data to send.

Failed to save picture '*'

Error text: "Failed to save picture '*'. The picture might be corrupt, try uploading the picture again or use another picture."

Something went wrong when uploading one or more pictures. Several instances can be present in the same response.

Recommended action: Try uploading the picture again.

Example:

Syntax error

Error text: "*. Line *, position *."

There is a syntax error in the imported XML. This is typically caused by unescaped special characters: '&', '<' and '>'. See the section for more details.

Recommended action: Make sure you are encoding special characters correctly: once to get them into the import XML and then once again to get them into the SOAP-object.

Example:

Guid *

Error text: "Guid *"

You have done too many revisions and the version number has gone out of bounds.

Recommended action: Contact Shoppa.

Example:

Validation error

Error text: "Line: *, Position: * "*""

The imported XML does not match the XML-schema.

Recommended action: Adjust the generation of the XML content according to the given reason.

Example:

Deadlock found when trying to get lock

Error text: "Deadlock found when trying to get lock; try restarting transaction"

Something went wrong serverside.

Recommended action: Wait a while and resend your data.

Connection must be opened

Error text: "Connection must be opened."

Something went wrong serverside.

Recommended action: Wait a while and resend your data.

Lost connection to MySQL server during query

Error text: "Lost connection to MySQL server during query"

Something went wrong serverside.

Recommended action: Wait a while and resend your data.

Failed to create new session

Error text: "failed to create new session"

Something went wrong serverside.

Recommended action: Wait a while and resend your data.

Exception has been thrown by the target of an invocation

Error text: "Exception has been thrown by the target of an invocation."

Something went wrong serverside.

Recommended action: Wait a while and resend your data.

Lost connection to backend server

Error text: "Lost connection to backend server."

Something went wrong serverside.

Recommended action: Wait a while and resend your data.

An exception occured that could not be fully serialized

Error text: "An exception occured that could not be fully serialized: Exception has been thrown by the target of an invocation."

Something went wrong serverside.

Recommended action: Wait a while and resend your data.

This describes StoreInfo schema version 1.6.

While most product information is static over time, prices are not. Stores have different prices for the same product and prices change at different times. This information is stored in pricelists which is one kind of StoreInformation package.

In contrast to products and campaigns, pricelists are not automatically inherited along the customer tree. A store uses the pricelist named STANDARD from its own node by default, but a named pricelist from a parent node can be explicitly selected instead.

Pricelists are described by packages with a name and a start date, but no stop date. If no name is provided, the default name STANDARD is assumed. If you also provide a package id, you can later use this to refer to that package instead of using name + start date.

Mediablob primarily identifies packages by id + countryCode. If id is not provided, the package is identified by name + countryCode. We recommend using the id for identification when possible. This behaviour is different from previous versions of the api and should be considered when updating existing integrations.

Prices are changed by sending a new package with the same name for a later date.

Lets build a pricelist from scratch and see how it evolves with different requirements.

A basic pricelist

Lets say store S123 wants to sell our sample product for 205 SEK. The price is valid from September 21st, 2008. The corresponding xml format for creating a standard pricelist is:

Creating a named pricelist

Some stores may use a mutual pricelist. In this case HQ wants to publish a named pricelist the stores can subscribe to. We create the same pricelist above as a named pricelist. We use an id from the HQ ERP system for future tracking and updates. Here is the xml we need:

Adding a product to an existing pricelist

Now we want to add two other products to the named pricelist. The xml for this is:

After this, the pricelist contains three priced products.

Deleting a complete pricelist

We finally decide to restructure our pricelist system and want to delete a pricelist completely. We do this by setting the delete attribute but omitting the startDate. The xml for this is simply:

Removing a product from the pricelist

In addition to deleting a complete pricelist you also have the option to remove a selection of products from the existing pricelist. Instead of defining the delete attribute in the package tag, it will be set in the product tag. The xml for this is simply:

This describes SignOrder schema version 1.1.

A signorder file can reference a number of products, which display groups that should be used to print them, and how many copies should be printed. Additionally you can specify values for the product fields (e.g. price, text1, etc.). Note that these values will not override existing product fields, but will only populate empty fields. The exception to this is the price field, which will override existing prices.

Other notes:

• To specify values for code fields (Code1, EAN13, etc.) you need to use the <code> element, rather than the <field> element.

• To get multiple products onto one template they need to be grouped in a products element. Which display group to use should then be specified for the products element, and not the individual product elements. In this case the product elements need to have the productIndex attribute, in order to specify which product index to use in the template(s).

• The usageDate attribute can be used to get prices from future dates. If omitted, todays date will be used.

• If the autoPrint attribute is false, there is no need to specify display groups.

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.

Deleting a text field

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.

Deleting language support

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.

Replacing all texts for a language

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!

Deleting an entire product

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.

Display groups

Display groups are managed through the Shoppa client. Each display group can reference multiple layouts and formats of multiple templates, and also a different number of copies for each. The most common use case is one copy of one format/layout/template.

DisplayGroups.xml

The file DisplayGroups.xml is located in the sub folder Schemas in the hot folder. It is automatically generated by the Shoppa client, and contains information about the available display groups. It could look something like this:

Each group has a name, an Id and at least one member, groups without members are omitted from the file. Each member references a template, a layout, a format and a number of copies.