Introduction

ECommerce API is an alternative way of accessing data stored in Perfion. Perfion systems include a Perfion API in which you can access data in Perfion. The Perfion API supports a general purpose Query Language that is a powerful yet simple way of getting data out of Perfion.

The ECommerce API is focused on delivering data for ECommerce Systems like Shopify, Sana, DynamicWeb etc. and is designed specifically for that purpose. EC will therefore never replace the Perfion API but will coexist alongside it. In fact, internally EC utilizes the Perfion API.

Typically when delivering data to ECommerce systems you focus on delivering data on Products, Categories and maybe even sites. Perfion can hold any entity, but the ECommerce API, at the time of writing, supports only the four entities Site, Category, Product and Variant.

Here you will discover how to configure the ECommerce API so you can make it possible to execute very simple yet powerful requests like GetProducts, which gets all products in Perfion with variants, categories etc. in a format more or less ready for delivering to the ECommerce System.

The model in ECommerce API

The EC supports four kinds of entities:

• Products

• Variants

• Sites

• Categories

Product

A product in EC is the most important entity. In Perfion, a product is simply a feature with a configuration. As Perfion users would know, that means that a product can hold almost any kind of data. From the simple types strings, numbers, dates to images and files. All values can be both localizable, that is have different values depending on the language, and be multi value, that is having more than one value for a single product. EC API supports transporting and mapping more or less all these values into an ecommerce-friendly format.

Variant

A variant in EC is a version of the product. A variant of a product has at least one feature value that distinguishes it from the other variants of the same product. It could be a colour feature that on one variant holds the value “Red” on another it is “Green”. The feature or features that distinguishes a variant from all other variants of the same product are called variant dimensions. Typical variant dimensions are “Colour”, “Size” and “Model” but it can be almost anything. Perfion supports any number of variant dimensions, but the ecommerce system you are using can limit that number. Usually at least three dimensions are supported.

Site

A site holds all information interesting for a site. In Perfion it is all still simply a feature with a configuration. In many ecommerce systems you tell what there is to tell about a site (also sometimes called a shop) in that system itself, and hereby does not need to define anything on a site, maybe with the exception of its categories. 

Category

A category in Perfion is often a hierarchical structure that categorizes all products. In a coffee shop categories could be called “Cups”, “Jugs”, “Coffee machines” etc. etc. As the other entities, a category is simply a feature with a configuration. Again, this means that it can hold more or less any data and that data can be accessed through EC. Categories and sites must share the same base feature to be accessible by EC.

As an example, consider the screen shot below in Figure 1. This shows a site named “My Site”. The site holds four categories: Coffee, Brewing, Keeping warm and Accessories and the Keeping warm has 13 products (in this case jugs) in it.

As can be seen the physical jugs seems only to be distinguishable from each other on their color, so the 13 jugs could be 13 variants of the same product varying on the Color feature.

EC defines how products and variants must be configured in order for it to recognize the topmost item (named EM77) as a product and the remaining 13 items as being its variants. This configuration has not been done yet and hereby not shown in Figure 1, but will be done later in this document.

Open

Figure 1: Example of how sites, categories and products/variants could be laid out in Perfion

Installing the ECommerce API

The configuration of the EC is stored in Perfion. It is simply a set of features which are recognized by their names. All features used by the ECommerce API have their names prefixed “ECommerce”. If you do not have these features, they can be created by running Ecommerce API - Features and Data Install in the Settings > Integration section of Perfion.

Open

Creating your first channel

First, we need to define a so-called channel. A channel in EC is a “unit of configuration” in Perfion. We will get back to that concept later (chapter Channels in Ecommerce API), but here it suffice to say that it allows you to have multiple channels and they can be configured differently in order to deliver different data in different formats to different ecommerce shops.

Go to the Feature Data-section and find the ECommerceChannel-feature. On the right hand side, define a channel as done in Figure 5 below.

In the figure, it is called “My Channel”. You can choose whatever name you like, but if you name it differently remember to update the examples later in this document. Note the auto-created channel named * (star). It is not a real channel, but used later to designate that this setting, mapping etc. is to be included for all channels and not only a single channel. Simply leave the *-mapping in there.

Creating your first mappings

Having created My Channel let us turn to define a few mappings. Click the ECommerceMapping-feature and create the first mapping. The first mapping you create should be the so called a Context-mapping. For each channel and each entity, you want to access, a context-mapping needs to be there in order to tell EC where to find data for that entity (in which configured base-feature). Let us therefore create a Context-mapping for the entity Product on Channel “My Channel”. It looks like shown in Figure 6:

The base value of the mapping should hold the name of the base-feature of the feature you configured for holding, in this case, products. In the “Coffee demo” (and in many other Perfion installations) it is a feature named Product, so I type that in the first column named ECommerceMapping. The Context-Mapping can do other tricks, but for now it suffice to know that it is simply naming the base-feature for the entity.

As ECommerce Output Kind or just “Output Kind”, you pick “Context” from the drop down list. The output kind is important when defining a mapping, since it tells EC both something about what kind of data it can expect and something about what kind of data should be output. Finally, you pick the entity, which is “Product”, and which channel this mapping belongs to, in our case “My Channel”.

This is actually enough for EC to start working with products! It would be boring products though, since we have not said anything about what data (which features) we need from those products, so let us continue doing a few more mappings before putting EC into action.

In Figure 1, we saw a few products from the Coffee Demo. Notice here that we have the unique Item Number in the feature with caption Item Number. We have the name of the product in a feature captioned Item Name and we have images of the products in the feature captioned Image. Finally we have a feature captioned “Description” holding a description of each product. We have many more features, but let us stick to only create mappings of these.

Figure 7 below shows 4 mappings that have been added.

A mapping should be read left to right:

1. In ECommerce Mapping you have the “from” feature. Notice that when asking for the base-value on, in this case, a Product, we write Value in the leftmost column.

2. In ECommerce Output Kind the type of the mapping is picked. We have already seen Context but in the above we tell that for example Value hold the unique key of each product (Output Type set to KeyField), content of ItemName and Description should be output as fields and finally that the value of the Image-feature should be output as an Image. More on Output Kinds.

3. ECommerce To should hold the name given to the output data. This should be a name picked that makes sense to the receiving ECommerce System. In the above, we see that we for example have picked Item No for the field holding the unique key and Description for holding the description.

4. Finally ECommerce Entity and ECommence Channel are mapped to Product and My Channel, respectively.

Most mappings take data from some feature and outputs it somewhere in the results returned by EC. Context mapping is an example of a mapping that does not produce any output and therefore does not need anything written in ECommerceTo. There are a few other output kinds associated with variants that also does not produce any output. We will get back to them in chapter Enabling Variant Support in ECommerce API.

Creating your first EC request

Now we are ready to check the result by sending a request to EC. In the Perfion Client this can be done the exact same way as running a Perfion Query. Perfion simply recognizes if a query is an ECommerce Request and sends it to EC, if that is the case. If it is not, the “normal” Perfion API will handle it as usual.

Try going to the Perfion Query Analyzer, picking the “Get Products”-sampling query and modifying the channel name to My Channel or whatever channel name you chose in section Creating your first channel. You should end up with a result similar to this:

As you can see this request actually only tells EC which channel you would like to get products from, but since you already told EC where it can find products for this channel, and which features you want output and how, EC can do its work from here.

The above request will get all products from Perfion, so it may take a few seconds (or many hours!) depending on the size of your database. Below a single Jug is shown, which is part of a result containing a total of 122 products:

This is actually it! You have now learned the basics of EC. In the following chapters, we will go into much more detail on the more advanced parts of EC.

Read more: