Perfion/Sana Connector 3 Connector 3.0.pdf · This document is about the 3.0 connector or rather connectors, because there are two of those: One for Sana Commerce 9.1.4-9.2.x and

Perfion

www.perfion.com

Document version: 3.0.0 rev 9 (includes Sana Connector 3.0.6 and Perfion 4.5 2019 R2-features)

Document date: 2019-09-24

Copyright by Perfion

Perfion/Sana Connector 3.0

For Sana 9.1.4 and later

and

Perfion 4.5 2019 R1 and later

http://www.perfion.com/

Perfion/Sana connector 2 of 73

Contents

1. Introduction ............................................................................................................................................................ 3

Applicable versions ....................................................................................................................................... 3 The basics of what this connector does ........................................................................................................ 3 Changes from 2.0 to 3.0 connector ............................................................................................................... 4

2. Installation .............................................................................................................................................................. 8

Prerequisites ................................................................................................................................................. 8 Installing the connector in Sana .................................................................................................................... 8

3. Configuring the connector for the first time ............................................................................................................ 9

Configuration in Sana .................................................................................................................................... 9 Configuring the connector for the first time in Perfion ................................................................................. 13

4. Creating mappings for Sana ................................................................................................................................ 34

Mapping to fields - Output Kind KeyField .................................................................................................... 34 Mapping to fields - Output Kind Field .......................................................................................................... 35 Mapping to fields - Using a Wild Card-mapping .......................................................................................... 38 Mapping to images ...................................................................................................................................... 41 Mapping to attachments .............................................................................................................................. 43 Mapping to related products ........................................................................................................................ 45 Mapping to related categories ..................................................................................................................... 46

5. Customizing Sana ................................................................................................................................................ 48

Decorating Fields using attributes ............................................................................................................... 48 Grouping information in GetEntityFields ...................................................................................................... 50

6. Setting up variants ............................................................................................................................................... 57

Settings ....................................................................................................................................................... 58 Mappings .................................................................................................................................................... 58

7. Creating multiple shops ....................................................................................................................................... 63

8. Debugging the connector and connector setup ................................................................................................... 64

9. The Image Cache ................................................................................................................................................ 66

Enabling the Image Cache .......................................................................................................................... 66 Example ...................................................................................................................................................... 71 Troubleshooting .......................................................................................................................................... 72 Final remark regarding disabling the cache ................................................................................................ 73


1. Introduction The Perfion Connector 3.0 for Sana is like its predecessor version 2.0 a so-called extension to Sana. A concept that

was introduced in Sana Commerce with version 9.1.4.

Applicable versions This document is about the 3.0 connector or rather connectors, because there are two of those: One for Sana

Commerce 9.1.4-9.2.x and one for Sana Commerce 9.3.0 and later (from now on just called Sana). The main

difference between the two is that Sana 9.3.0 and later supports SaaS, i.e. Sana running in the cloud as opposed to

on premise. Predecessors of Sana 9.3.0 only supports running on premise.

There are two other connectors are versioned 2.0.x. Again, there is one for Sana 9.1.4-9.2.x and one for Sana 9.3.0

and later, respectively. This document is not covering these connectors, so if you are implementing one of these,

please switch manual.

Table 1 below summarizes the four connectors available in 4 different packages

Package Sana Version required Perfion version required Covered by this manual

Connector 2.0.x for Sana 9.1.4 – 9.2.x From 9.1.4 to 9.2.x All Perfion 3.5 and up No

Connector 2.0.x for Sana 9.3.0 and up From 9.3.0 and up All Perfion 3.5 and up No

Connector 3.0.x for Sana 9.1.4 – 9.2.x From 9.1.4 to 9.2.x From 4.5 R1 2019 and up (Version 4.5.52)

Yes

Connector 3.0.x for Sana 9.3.0 and up From 9.3.0 and up From 4.5 R1 2019 and up (Version 4.5.52)

Yes

Table 1: Which connector versions/packages fits which Sana and Perfion versions.

From here on, when the manual just says “the connector” or “the 3.0 connector” it means any of the two 3.0-

connectors.

The basics of what this connector does What this connector does is that it allows products in you ERP-system to be augmented with more and “richer” data

coming from Perfion.

Without the Perfion Connector, Sana (depicted very simplistic) works as follows:

Figure 1: Sana connected to ERP System

Sana asks the ERP-system for data, that can be products, product categories, orders, customers etc. etc. and the

ERP-system will provide that data. Sana can also create data (orders, customers etc.) in the ERP system (not shown

in the above figure).

With the Perfion Connector, Sana instead asks the connector for data and does not go straight to the ERP. In most

cases, the connector will simply relay the call, i.e. forward the call to the ERP-system, and return to Sana exactly what

the ERP system returned to the connector.

In a few, but important, cases, however, Perfion will not only go to the ERP-system to get data. It will additionally

augment the ERP-data with additional data found in Perfion. It works as shown in Figure 2:


Figure 2: Sana connected to ERP system utilizing the Perfion Connector

Mainly it is the “Get Products”-call from Sana, which will have its data augmented heavily from Perfion.

Changes from 2.0 to 3.0 connector The two connectors do the same thing: Augment data coming from an ERP system with data from Perfion. There are,

however, a few things that separate the new connector from the 2.0-version:

1.3.1 ECommerce API

The new connector communicates with Perfion through the ECommerce API. First, this means that setting up and

configuring the 3.0 connector is different from how it is done in the 2.0 connector. In the 3.0 connector, you set up a

Channel for Sana in the ECommerce API, while you in 2.0 connector had a separate setup dedicated for Sana. For

the implementer being used to the ways of the 2.0 connector this change is not a big deal, since the ECommerce API

is heavily inspired by how the Sana 2.0 connector worked.

The move to the ECommerce API also means that migrating an installation from a 2.0-connector to the 3.0-connector

requires migrating the setup from the Sana-setup to the ECommerce API setup. It is a reasonable simple but

unfortunately manual task.

A good understanding the ECommerce API is a great help when setting up the connector. Likewise can the

ECommerce API-manual also be of great help. This can be downloaded from Perfion Knowledge Base.

Figure 6 illustrates how the Perfion Connector 3.0 works in slightly greater detail:


Figure 3: Overview of the steps involved in

Following the direction of the arrows from the initial Sana request, we have:

1. Sana issues a request

2. The Perfion Connector intercepts it and calls the ERP with the same request. Note: Some requests, though, does not go to the ERP and are answered by the connector alone. GetCategories is an example of a call that has this behavior.

3. ERP returns a Sana response, i.e. it has a format understandable by Sana.

4. The connector gets that response and in many cases does not do anything but pass it back to Sana.

5. In some, but very important, cases, though, the result together with the original request is used to formulate an ECommerce API method.

6. This ECommerce API method is executed and an ECommerce API result is passed back. As we later will

see that although this resembles a Sana response, it is not exactly the same.

7. The connector merges the original response from the ERP-system with the result from the ECommerce API and returns the final result to Sana. This result is a Sana-response.

1.3.2 Multiple stores

The biggest benefit of using the ECommerce API is that it allows multiple web stores to be set up and configured.

These are called channels in the ECommerce API. Another benefit is that the ECommerce API can be configured to

support a multiple different ECommerce-systems and is not only targeted towards Sana. See chapter 7 on how to set

up multiple stores.

1.3.3 Wild card-mapping

Another benefit of using the ECommerce API is that it (from 4.5.52) supports a so-called wild card-mapping. Briefly

described, this allows you to map any number of “simple fields” by creating just one mapping.


With the 2.0 connector the implementer was forced to create a single mapping for each and every featured needed to

be mapped to the ECommerce API. That could be tedious for customers having hundreds or maybe even thousands

of features.

Now using the wild card-mapping, the 3.0 connector these can all be mapped clicking a simple checkbox as part in

the general and creating a single “all-encompassing” mapping. There are a few restrictions on, which features can be

mapped this way. Section 4.3 describes how this work.

1.3.4 Which Sana methods are having their behavior affected by the Connector?

Perfion overrides the behavior of the following calls from Sana, relaying all other calls straight to the ERP-system:

GetEntityFields (for products only): Here the ERP-system is still called, but Perfion extends the returned list

of fields with whatever fields that are created in Perfion. These are so-called “Extra fields” or “Custom fields” in Sana. All fields coming from Perfion can be recognized by having their name prefixed with “Perfion__” (The letters “Perfion” followed by two underbars).

GetProducts: The ERP-system is still called by the connector, but the products returned will have their data

augmented with data from Perfion. That will be the custom fields, Related Products, Attachments and Images. In case the GetProducts returns variants, and have variants been set up in Perfion, these will have their data augmented the same way.

GetProductCategories: This method will be answered by Perfion alone returning the category structure.

GetProductImages: The Connector assumes that all images on products are to be found in Perfion, so this

method will be answered by Perfion alone. It simply, for each product and variant, returns the list of images on each.

GetProductImageFile: This method is also answered by Perfion alone, returning the binary data for each file

returned by Get Product Images previously.

GetAttachmentFile: The Connector assumes that all attachments on products are to be found in Perfion.

Attachments are added to products in the Get Products-call, and this method (called by Sana afterwards) will supply the binary data for attachments of file type (as opposed to url-type attachments).

TestConnection: The connector both checks the connection to the ERP-System and the connection to the

Perfion API and only if both connections are working an “OK” is returned to Sana.

1.3.5 Available in the Sana Store

The 3.0 connector for Sana 9.3.0 is available from the Sana Store.

1.3.6 Time zone differences between Sana and Perfion can now be accommodated

Requires connector 3.0.1

Sana and Perfion does not run in same time zone. If not accommodated for, Sana can miss updates being done in

Perfion. See section 3.2.3 for detail on how to set that up.

1.3.7 Possible to retrieve related products, attachments and categories from ERP

Requires connector 3.0.1.

Now you can choose to maintain categories, related products and attachments in you ERP system, and have those

passed to Sana using the Connector. Version 3.0.0 required you to maintain all the above Perfion. See section 3.2.3

for more information.


1.3.8 Possible to output “units” for features having such

Requires connector 3.0.1 and Perfion 4.5 R2 2019.

This can be done in two different ways as described in sections 3.2.3 and 5.1.

1.3.9 Possible to pass the feature grouping constructs in Perfion to Sana

Requires connector 3.0.1 and Perfion 4.5 R2 2019.

In Perfion features can be grouped in so-called Top View Groups and View Groups and be assigned to Views. Both of

these are now passed to Sana as part of the GetEntityFields-call. See more in section 5.2.

1.3.10 The connector can run in a configuration where you have variants in ERP-System but not

in Sana


This special configuration is now supported. As long as VariantSupportEnabled is not set to true, the connector will

pass any variant information coming from ERP-system on to Sana “unchanged”. Previous versions of the connector

only passed in part of it.

1.3.11 Image Names passed to Sana now contains culture and file name


Sana does not support shipping any information to it as part of the GetProductImages-call except for ProductId,

VariantId and ImageName. As an image name previous versions of the connector simply used the GUI needed by

Perfion to identify the Image added a file extension. From version 3.0.2 the connector encodes the culture (if any) and

the file name stored in Perfion to it. More details can be found in section 4.4.1.

1.3.12 Image Cache added

Requires connector 3.0.3 or even better 3.0.4, since it remedies a bug persisting the Image Cache.

The Perfion Connector has always been handling the GetProductImages and GetProductImageFile-methods. Sana is

a bit eager on how often these two methods are called and in some cases get overburdened by the many images that

gets returned. The Image Cache is a way to avoid that the same image is shipped to Sana more than necessary.

More details can be found in chapter 9.


2. Installation

Prerequisites Before installing the connector make sure, you have the following:

1) You have a running Sana Installation connected to some ERP-system. Sana version must be at least 9.1.4

and can be either running in the cloud (only 9.3.0) or on premise.

2) You have a Perfion Database v 4.5.

3) You have a Perfion API set up on IIS Perfion running at least 4.5 2019 R1 (internal version 4.5.52). The Perfion API endpoint must be accessible from the server running both the front- and back-end of Sana.

4) You have a Perfion Windows Client. Any 4.5 version of Perfion will work, but it is recommended that the Perfion Client is at least 4.5 2019 R1.

5) Your Perfion license must include licenses for the Perfion API and the Sana Connector.

6) You are acquainted with how both Sana and Perfion works to some degree.

Installing the connector in Sana For installation in Sana 9.3, please refer to this article on how to install Sana apps:

https://help.sana-commerce.com/sana-commerce-93/user_guide/sana-apps/what-are-sana-apps

For installation in older versions of Sana (9.1.4 - 9.2.x), the installation is a manual process. For more information

about how to do this, please contact your Sana Partner, or the Sana Consultancy team.

https://help.sana-commerce.com/sana-commerce-93/user_guide/sana-apps/what-are-sana-apps


3. Configuring the connector for the first time This chapter takes you through all configuration needed in order for setting up the connector for the first time. First

section will take you through the necessary steps in the Sana Admin-interface. Next, in Section 3.2, will take you

through the steps needed in Perfion.

When you have completed this chapter, you indeed have a very basic setup of Sana with the Perfion Connector.

Configuration in Sana Note: This section assumes that you are using Sana 9.3.0 and hereby is implementing a so-called Add On (The

connector). See Sana Documentation in order to find the so-called Perfion Extension in the Sana-interface.

After the connector has been installed, it needs to be configured in order for it to reach the Perfion API. This

“connection to Perfion” is almost the only thing you need to configure in Sana, since the rest of the configuration

resides in Perfion.

In Sana Admin, go to Apps -> Add-ons and pick any of the tabs. The list of “Installed add-ons” will contain “Perfion

Add-on 3.0”, so simply hit the “Configure”-button for it. This will bring the dialog shown in Figure 4.


Figure 4: A sample configuration of the Perfion Connector in Sana Admin

Web Service Url: Here you type the full URL to the Perfion Web Service API. This is the source for data from Perfion.

The connector accesses the ECommerce API provided by that service.

Logging: Enable logging in order to log all calls from Sana, all data fetching and data transformation done by the

connector. This logging is quite verbose, and should only be enabled when configuring and debugging an installation.

See more in chapter 8 on how logging is viewed.

From Connector version 3.0.5 you can additionally choose to log to the Perfion Add-on Storage. This only makes

sense, when you have access to that storage from for example File Explorer. You are likely only to have that when

running your Sana On-Premise (as opposed to in the cloud). When running ON-Premise you will find these log files in

the folder \@data\packages-data\Perfion where Sana is installed. Logging to Add-on Storage creates files suitable for

debugging the communication between Sana, ERP and Perfion. The files created are quite similar to those created by

the 2.0-connector, for those familiar to that. When logging to Add-on storage you additionally have the option to prefix

all filenames with a timestamp. That way you can log everything that happens over a time period. Be aware, though,

that these log-files might take up considerable space and they are not cleaned up automatically. Another warning: Be

careful when deleting all the debug-files not to delete the file named “imagecache.xml” (if enabled). IF you accidentally

delete it, though, it will turn up again provided you do not recycle the site.


Enable Image Cache and Image Life Time controls an Image Cache added to the connector in version 3.0.3. These

settings will be described in chapter 9.

Ignore Errors From ERP: Normally, when the Perfion connector calls the ERP, any errors returned from the ERP will

make the Connector simply return the result (the error) from the ERP to Sana, without trying to augment the result

with data from Perfion. If this setting is on, however, such errors will not stop the connector from going to Perfion

augmenting the data.

Note: Even with this setting on, the errors from ERP are still returned to Sana. Normally this setting is only on during

an implementation phase.

Refresh configuration on every call: The connector caches the entire setup made in Perfion (Mappings, Settings

etc.) in order to work as fast as possible. Only when Sana calls the “GetEntityFields”-method this internal cache is

refreshed. Enabling this setting will refresh this cache on every call to the connector, so that changes in the

configuration in Perfion is immediately reflected on next call.

This is helpful when doing changes to the setup to have them immediately reflected in Sana.

This setting should only be enabled when configuring and debugging an installation, since having it enabled slows the

connector.

Bottommost you will find the Version of the connector together with the version of the called ECommerce API. The

later can only be retrieved, if the Web Service Url is filled out and there is an answering ECommerce API at its

endpoint.

Test Connection Mode: Sana quite frequently calls a method named “TestConnection” to test whether it has

connection to ERP. If this call continuously fails, say, 3 times Sana will go into “Maintenance mode” meaning a lot of

things, for example that the order process is hampered. Introduced in Connector 3.0.5 you now have the option to

choose whether the connector should only call the ERP or both call the ERP and Perfion when Sana tests whether or

not a connection is available. Since Perfion is not involved in the order processing it is recommended to switch this to

“Only ERP”. For those used to the 2.0 connector, this was indeed how “TestConnection” was handled there.

The Test Connection button (not to be confused with the above described “TestConnection”-call done by Sana

“behind the scenes”) tests that the Connector is configured correctly. Before Perfion is configured, you will get an error

as the example shown in Figure 8. In the example we can see, reading the red message from top to bottom, that the

Web Service Url does indeed point to a Perfion API, that the ECommerce API is installed with version at least 4.5.52

but the connector complains that it does not find any Channels set up for Sana (known as stores or web sites in

Sana).

Figure 5: Clicking Test connection when something in Perfion is still to be configured.

Table 2 below lists all the possible issues you can get from clicking “Test Connection” and which steps should be

taken to correct them. Each issue will all make the test list show up in red as shown in Figure 8.


Error message Description Solution

Perfion Web Service... Failed The connector cannot call the Perfion API pointed to by the Url.

Check that the Web Service Url in Sana indeed points to a Perfion Web Service and that this end point can be reached from the Server running Sana. Check that the Perfion API is correctly configured and can connect to the Perfion Database. Note: Test Connection tests only back end. The Sana front end must be able to reach the Perfion API as well.

ECommerce API configured... Failed

The Perfion API installed does not support ECommerce API.

Upgrade the Perfion API to version 4.5 R1 2019 (4.5.52) or later.

ECommerce API must be at least version 4.5.52... Failed

ECommerce API installed must be version 4.5 R1 2019 (4.5.52) in order to support methods called by the Connector.

Upgrade the Perfion API to version 4.5 R1 2019 (4.5.52) or later.

0 Sana Store(s) found... Failed

There needs to be at least one Channel in the ECommerce API that has ECommerce System set to “Sana” (without quotes) In Connector versions previous to 3.0.4 you would get this if your license did not include “Sana Connector”.

Create a channel associated with ECommerce System “Sana”. See section 3.2.2 on how to set up a Channel in Perfion.

Missing license to use Sana Connector… Failed (Connector version 3.0.4 and later)

You need to have license for Sana Connector.

Contact Perfion Support to obtain a Perfion License File containing license for Sana Connector.

Failed to retrieve configuration for Sana Store(s)... Failed

For some reason the configuration for all channels marked for Sana cannot be fetched.

This should really never happen. If problem persists please Contact Perfion.

“x” Image Service(s)... Failed At least one Perfion Image Service cannot be accessed by Sana.

Make sure the ImageUrl-setting is correctly typed for all channels associated with Sana. The Url typed must be accessible from Sana (back end). The Image Server is not accessed by the server running the EC API but directly by the connector. Unless (of course) the EC API is accessed through other means than the Connector. See section 3.2.3 for more information.

“x” File Service(s)... Failed Same as above, just for the File Services.

Same as above, just for the File Services.

Table 2: The list of issues that can be met clicking “Test connection” and measures on how to remedy them

The next section, Section 3.2, will take you through the steps necessary to configure Perfion. When that is done,

clicking “Test connection” should give a result similar to the one shown in Figure 6.


Figure 6: Clicking Test connection when everything is OK

3.1.1 Where are the missing settings known from 2.0?

The old Connector 2.0 had a few more settings. In that version, you could set two additional urls pointing to an Image-

and a File-service, respectively. Furthermore, you had the possibility to switch between the “Advanced” and “Simple”

mode.

These settings are gone for two different reasons:

1. Image and File-server urls are found in the ECommerce API settings, so they are no longer needed in the Sana Admin interface.

2. Simple and Advanced mode relied on accessing file folders in the Starter Site. This option has been removed as part of making the connector “cloud aware”, i.e. it may no longer access files in the Starter Site.

As a consequence of item 2, the possibility of customizing the connector using customized xsl-documents, known

from the 2.0 connector for 9.1.4-9.2.x, is no longer available in the 3.0 connector.

Configuring the connector for the first time in Perfion This section will take you through all the necessary steps to make a first simple configuration.

3.2.1 Auto create features and configuration for the ECommerce API

First step in order to configure the ECommerce API is to a set of features and feature values allowing giving a start of

point. Since Perfion version 4.5.31, it has been possible to auto-create these features and feature-values. In Perfion

4.5.52 a few new Output Kinds (and some other features not related to Sana) have been added, so it is recommended

to use this version (or higher) when running the auto creation tool. If you already have created these features using an

older version of Perfion, it is not a problem. Each section using one of the new Output Kinds will guide you to creating

it.

This section takes you through the few steps needed to auto create features and feature values needed for the

ECommerce API to work.

Start Perfion and make sure it is version 4.5.31 or later. Even better: Make sure it is version 4.5.52 to get the latest added Output Kinds.

In Perfion main windows, while holding “Ctrl” click the document icon in the top left corner. This will bring out a small menu, click “Options” and you will see the “Developer Options”-dialog. Here you simple click “Install” for “Install ECommerce API Features and Data” as shown in here:


Figure 7: Installing the ECommerce API in Perfion

Important: It is always advised to do a backup your database before doing operations like this.

Answering “Yes” in the “Are you sure”-dialog will start the process and it will take about 5 to 10 seconds, depending

on your hardware, to complete. A message-dialog will show up when done.

Note that it is still possible to install the features needed to configure the 2.0 connector, but they will not be needed in

any way by the 3.0 connector. It is, however, possible for the two connectors to co-exist. This can be pretty handy

during a migration process, where the Old 2.0 connectors runs from the old settings and mappings while ECommerce

API settings and mappings are being built for the 3.0 connector.

When completed you have the features and configurations needed to set up the ECommerce API and hereby also to

set up the 3.0 connector.

To see the most important of the features that have been added, go to “Feature Data”, then expand the “String”-

features node and finally expand the “ECommerce Features”-node. Here you will find seven selectable features where

some needs to be filled out by you and the rest can and should be left as is. In Figure 8 one of the features, the

ECommerce Settings, are shown (what alt these means are addressed later):


Figure 8: The ECommerce Settings within Perfion for the Connector

Below is an overview on what each of the ECommerce-features on the left hand side contains:

ECommerce Channel: Here you create all the channels you needed. Roughly speaking, you will need a

channel per output channel. For the Sana Connector you are likely to need a channel per website/shop.

ECommerce Entity: Here are a list of all entities supported currently by the ECommerce API: Site,

Category, Product, Variant and Language Deviation. This is used internally by the connector and should not be modified.

ECommerce Mapping: Here you find all mappings from Perfion to some Channel (that is, to Sana). A

mapping is a way of expressing that “X in Perfion is called Y in Sana”. All mappings can be edited by clicking this node. This is where the main part of the configuration of the connector will take place, and we will do that in section 3.2.

ECommerce Output Kind: Here is a list of all the Output Kinds, that is, ways of expressing how the “Y” from

previous item should be output knowing “X”. All the different output kinds usable in Sana is described in chapter 4.

ECommerce Settings: Here you find the settings needed to set up the Connector. These are the ones

shown in Figure 8. We will get back to these settings in Section 3.2.3.

ECommerce System: Here you will find a list of ECommerce Systems to pick from. Version 4.5.52 auto

creates four ECommerce Systems: Shopify, Ucommerce, Sana and Magento, since these are the systems recognized by Perfion and the systems for which Perfion provides a connector. If you are making your own output from the ECommerce API, it makes good sense to add a new ECommerce System to this list. Note: From version 4.5.52, when accessing the ECommerce API for data belonging to one of the known channels, it is checked that the Perfion license does include a license to connector used.


ECommerce Type: This is just a selectable feature that you will need if you want to use support for variants.

The two values here “Product” and “Variant” should not be modified in any way. Support for variants is described in chapter 6.

The next sections will take you through setting up an entire (although) small configuration of the connector.

3.2.2 ECommerce Channels

A Channel is the ECommerce API equivalence of a store (aka website) in Sana. Below in Figure 9 a single channel

named “AllisonNav” has been added and assigned to the ECommerce System Sana. Assigning it to the ECommerce

System Sana makes it recognizable as a channel used for Sana.

Figure 9: A single channel named “AllisonNav” has been added to the ECommerce API as a “Sana”-channel.

The name “AllisonNav” is not chosen to be chosen randomly. It must exactly match the Sana Web Site Id for the store

whose data should be augmented with data from Perfion. AllisonNav is a demo web site provided by Sana.

Note: The channel named “*” is not a real channel, but the item is there to allow picking the *-channel (“star-channel”)

which means “all channels”. More on the *-channel in chapter 7 where we discuss how to setup multiple channels,

and hereby multiple shops, in a single Perfion installation.


3.2.3 ECommerce Settings

Having added a channel (a store) and associated it with Sana will allow the “Test connection” in the Sana Admin-

interface to get a bit further. Now it should show the next issue (as compared to Figure 5 on page 3):

Figure 10: The next issue doing a “Test connection” is that Sana cannot reach neither the Image nor the File-server.

In order to fix that, let us go to ECommerce Settings to supply some settings for the ECommerce API (and hereby the

Sana Connector). We will add a Url to both the Perfion Image Service and the Perfion File Service.

Going to “ECommerce Settings” in Perfion will show all settings currently set up. In Figure 11 all settings have been

set up correctly (for some demo-setup):

Figure 11: ECommerce Settings.

The following describes the settings shown in Figure 11. The first 5 should be considered the minimum number of

settings:

Setting: ImageServiceUrl


This url should point to a Perfion Image Service usually installed in the exact same location as the Perfion API. The

Url should be on the form:

http://<server>:<port>/perfion/image.aspx

The Sana Connector will work without this url, but only in the rare case that no images come from Perfion.

Setting: FileServiceUrl

This works exactly as ImageServiceUrl, but is used by the Sana Connector for File Attachments. This Url should be

on the form:

http://<server>:<port>/perfion/image.aspx

Only in situation where attachments are not needed by some installation, you can avoid setting this up, but it does not

hurt to do it despite it is not being used.

Setting: Languages

Here you indicate which languages in Perfion that should be output to Sana. In this case, let us simply output English

and German to Sana (Perfion language name “EN” and “DE”).

Sana does not work with languages but cultures denoted by their LCID (a Language Code Identifier proprietary to

Microsoft). In section 3.2.4 we will see, how we make the ECommerce API translate from the Perfion Language to the

Sana LCID.

Setting: ImageHeight

This setting controls the height of all images sent to Sana. This is here set to 1024, but you can change it here if

wanted. Default value for this setting is 1024, so since we set it to exactly that in Figure 11 we might as well delete the

setting.

Setting: ImageWidth

Same as ImageHeight, except that it controls the width of the images sent to Sana rather than the height.

The next two settings require a bit more description

Setting: SanaTimeDifference (requires SanaConnector 3.0.1 or later)

Here you enter the whole number of hours (positive or negative) that tells the connector what the time difference is

between the Perfion Database Server and Sana.

Since Sana always uses UTC time, this amounts to figuring out what time zone the database runs in. Here are a few

examples:

Perfion runs in Central European Time (CET)

SanaTimeDifference should be set to -1, since Central European Time is one hour ahead of UTC.

Perfion runs in India Standard Time (IST)

SanaTimeDifference should be set to -5.5, since India Standard Time is 5 and a half hour ahead of UTC. Note that you must use a . (punctuation mark) as decimal separator.

Perfion runs in Pacific Time (PT)

SanaTimeDifference should be set to 7, since Pacific Time is seven hours behind UTC.

If you are unsure of what timezone your Perfion Database runs in, the difference can also be done in SQL Server

Management Studio using the query shown in Figure 12:


Figure 12: The SQL query used to find database time and utc-time.

As can be seen in the figure the database is 1 hour ahead of UTC Time (because it is in Central European Time), so a

-1 needs to be put in as time difference.

Query is repeated below for easy copy/paste to Management Studio:

select getdate() as databasetime, getutcdate() as utctime, DATEDIFF(hour, getdate(), getutcdate()) as SanaTimeDifference

Setting: SanaCaptionTemplate (requires Connector 3.0.1 or later)

Per default only the caption on features are sent as Caption on Fields to Sana. Same could be done with the unit, but

unfortunately there is currently the limitation in Sana that it does not support units on fields.

This limitation can been circumvented using the SanaCaptionTemplate-Setting in the connector. By setting this to

some value, a template, you can make the unit from Perfion part of the caption sent to Sana.

For constructing such a template, you have three tags available: %CAPTION%, %CAPTIONALTERNATIVE% and

%UNIT% each representing the similarly named properties on a feature in Perfion. In Figure 13, you see the feature

WeightKg which has a unit set to kg (short for kilo gram).

Settings: SanaCategoriesSource, SanaRelatedProductsSource and SanaAttachmentsSource (requires

Connector 3.0.1 or later)

These 3 settings controls whether categories, related products and attachments come from either the ERP-System,

Perfion or are completely disabled. They can be assigned one of the following values: None, ERP, Perfion.

Assigning one of them to ERP will fetch data from the ERP-system and ignore what comes from Perfion. This comes

in handy, if, say, you products are related in ERP-system and you want to avoid doing the same in Perfion.

If any of the settings are not set (or setting is there but set to blank), it means the same as setting it to Perfion, i.e. all

data comes from Perfion.


Figure 13: The feature WeightKg has its unit set in many languages

To output this to the Caption for the Field in Sana you could do a SanaCaptionTemplate as this: %CAPTION%

%UNIT%. This will output “Weight kg” in English for the WeightKg-feature. You can also add literals to the tags and

even put these literals within the tag, so that if tag is not filled out the literals will also not be output. Table 3 shows

different combinations of templates, captions and units.

Template Caption Unit Output to Sana Note

%CAPTION% %UNIT% Weight kg Weight kg

Weight Weight Space added after weight

kg kg Space added before kg

Space output

%CAPTION% (%UNIT%) Weight kg Weight (kg)

Weight Weight Space added after weight

kg (kg) Space added before kg

() Space and parenthesis output

%CAPTION%% (UNIT)% Weight kg Weight (kg)

Weight Weight

kg (kg)

Nothing output

%CAPTION (UNIT)% Weight kg Weight (kg)

Weight Nothing output

kg Nothing output

Nothing output

Table 3: Different templates outputting Captions and units depending on their values.

As can be seen from Table 3, the third template counting from the top seems to be the best template of the four, since

it outputs something sensible regardless of which of the combinations of features are used.

A few more settings are available

There are a few more settings in the ECommerce API than shown above. One of them, VariantSupportEnabled, will

be described in chapter 6. For information in the remaining settings, please check ECommerce API-manual.


Note how we for all settings have picked “*” as Channel name, despite that we in Section 3.2.2 created the

“AllisonNav” channel. We could indeed have picked that channel on all settings, but by picking the * we simply mean

“all channels”. So if we at any later moment create another channel, the settings with a * are already set for that

channel.

Important note: It is considered an error if you set the same setting both for the *-channel and for some other

channel, because the current ECommerce API reckons this as setting the same setting twice for that channel. This

might be relaxed in a future version of the ECommerce API (where the setting set explicitly on the channel would

override the *-channel setting).

The *-channel works the same for the entire ECommerce API most notable also for mappings, which is described in

the next sections.

3.2.4 ECommerce Mappings – Getting the cultures right for Sana

As noted earlier, Perfion works with Languages designated using the ISO 639-2 standard (with a few exceptions).

On the other hand, Sana uses cultures denoted by a LCID (Language. To make matters a bit more complicated, the

ECommerce API uses cultures as well, but is using the RFC 1766-standard for naming them. See Table 4 below for a

few examples:

Language Perfion Language ECommerce API Sana

English (America) EN or ENU en-US 1033

German (Germany) DE or DEU de-DE 1031

Danish (Denmark) DAN da-DK 1030

Dutch (The Netherlands) NLD nl-NL 1043

Table 4: Examples of Perfion languages and their equivalent ECommerce API- and Sana -cultures.

The solution is simple. In order to configure the ECommerce API to use other culture designators we, for each Perfion

Language, define a mapping and categorize it as a so-called “Language Deviation”. As we remember from section

3.2.3 we specified the languages “EN” and “DE” so it is exactly these two that needs to get mapped to a designator

suitable for Sana. This is done in Figure 14 below:

Figure 14: Note the two Language Deviations add the bottom.

3.2.5 ECommerce Mappings – For Products

Mappings are the single most important thing in the ECommerce API. Mappings is the place where you tell the

connector with what data each entity (Product, Variant and Category) in Sana should be augmented with.

In this section we look at mapping data on products.

If you want to go into detail on what the ECommerce API can output, the ECommerce API documentation will tell you

all there is to know about that. Here it should be noted, that not everything that can be done in the ECommerce API

makes sense for the Sana Connector, but most actually does.

To start creating mappings for our demo-products we use the “Coffee demo-database” and considers the two

products shown in Figure 15 below found in that database:


Figure 15: Two products in Perfion whose data we would like to map to Sana-

The 6 mappings shown in Figure 16 below will map exactly the products with the features shown in Figure 15 to Sana.

This section will continue explaining how these 6 mappings work.

Figure 16: The first 6 mappings made for all channels on the Product-entity

First thing worth mentioning is that a mapping should be read from left to right. In that order the features on a mapping

are:

Base value (often called “From”): Here you write what should be fetched from Perfion. In most cases you

would here have a feature name, but other options are available.

Output Kind: Here you describe how you want the “From” output. The examples later this chapter, will

describe exactly what to pick here in order to product the wanted output for Sana.

To: This is the name of the output made. This name might be recognized by Sana (Sana, for example,

knows what an Id and a Title is, but does not know what Brand is and hereby reckons that as a custom field).

Entity: The entity on which this mapping belongs (Category, Product or Variant for Sana).

Channel: The channel on which this mapping belongs. Here the *-mapping is used meaning all channels

Let us as an example read the 4th mapping in Figure 16: The value of the feature named GroupName should go to a

Field named Title for entity Product for all channels.

You can also see it as a mapping is answering 3 questions:

1. Question: Where can I get the data? Answer: Feature GroupName

2. Question: How should the data be output? Answer: As a Field

3. Question: How should it be named?

Answer: Name it Title

For those familiar with the ECommerce API will know that the ECommerce Output Kind, or simply Output Kind, tells

the ECommerce API how some data should be interpreted. Very often, this boils down to how some data should

output, but in a few cases, the feature simply holds some information that guides the ECommerce API without

necessarily outputting them.


Back to the 6 mappings in Figure 16. The first mapping is indeed a mapping that tells the ECommerce API

something, without anything being output. This mapping tells the ECommerce API, that you will find Products in

Perfion on the feature named Product. This sounds abstract, but it makes good sense. Perfion can be set up in many

ways and, as an example, hold many features that carries a configuration. In this first mapping we use the Output

Kind Context and that a Context-mapping is used to tell the ECommerce API in which feature the entities (here

products) can be found. That feature name is found in the left most column (the From-column), and here you indeed

see Product.

The second mapping tells the ECommerce API that the feature Value holds the unique Id for all products. For a

connector it is crucial to know which feature identifies a product uniquely. Those familiar with Perfion would know that

Value refers to the base value of (here) a Product. Note further, that it is mapped to the “similar” field in Sana, namely

the Id-field. Sana indeed uses “Id” as the unique identifier. So this mapping tells the connector which feature contains

the unique id of the products. When Sana asks for products it will ask for products by their Id, so the connector now

knows which products to fetch. As can be seen in Figure 15 the two products indeed holds a value that could

resemble a unique id, namely 1923-16 and 1923-18.

Both the above mapping does not bring any data from Perfion to Sana, which that Sana did not already get from the

ERP-system. They are both simply setting the scene. The final four mappings change that. They will all produce an

output.

The third mapping tells that the value of the Image-feature should be mapped to Image in Sana, and that it should be

output as an Image(Url). This means that the ECommerce API constructs an Image-element in the output holding

(among other data) and outputs that to Sana.

The fourth mapping maps from the GroupName feature to a feature Field named Title while the fifth mapping maps

the Description-feature to a Field named the same in Sana.

One thing worth noticing above all the mappings 2 – 5: They all map to something known to Sana. Sana knows what

the Id of a product is, and what its Image, Title and Description is. When addressing such “known names” in Sana,

Perfion will override the information coming from the ERP-system. Table 5 contains a table of all names that the

Perfion Connector considers known.

Name

Id Title Description

SortId

Visible Table 5: Field names reckoned as known

to Sana by the connector.

The sixth mapping maps the feature BrandName (the feature behind the Caption Brand shown in Figure 15) to a

Field named Brand. Brand is not a known field name in Sana, so the Connector will not override data coming from the

ERP-system but augment the product with a new field. This new Field is not named Brand, as one might expect, but

Perfion__Brand (Note that there are two underbars between “Perfion” and the name typed in Perfion, here Brand).

This prefixing is done in order for Sana to be able to distinguish fields coming from Perfion from other fields mainly to

help the user of the Sana Admin interface to recognize Fields coming from Perfion.

3.2.6 Testing the result – For products

With the settings and mappings of languages and products in place, we can go to the Sana Admin interface and test

the result of our effort.

Just before we do this, two things must be done prior to testing.


First of all we need a product in the ERP-system with an Id that matches one of the products we have in Perfion in

Figure 15. This can either be done in the ERP-system by making a new product with an id matching a product in

Perfion. Or maybe you have a product in the ERP-system, then just change the Id (the base value in our case) in

Perfion.

For this manual Sana has provided a cloud based-ERP system, in which I have created a few products matching a

few of the products in our “Coffee show” demo database. Matching ids of products is simple but crucial for the

connector to work correctly.


Figure 17: The matching of unique identifiers starting in ERP-system ending up on the Sana front end.

The second thing we need to do before testing is that Sana needs to know what it can expect of Fields from Perfion

on products. Sana gets that information through the connector by running the scheduled Task “Get information

import”. Simply go to Tools -> Scheduled tasks and hit the Start-button for that task as shown in Figure 18:


Figure 18: The “Scheduled Tasks”-list as shown in Sana.

Finally, we can test the result of all our efforts. To do this, it requires that your Sana-installation has “Debug Erp-

request”-enabled in its web.config. Check Sana documentation on how to do that. This is a highly recommended way

of testing the results.

If enabled you can go to Tools -> ERP connection -> Debug ERP request. Here you select the “GetProducts”-request

template and modify the following request parameters:

Remove ExtraFields-element (with sub-elements).

Remove MultiCurrency-element (just to avoid the many prices otherwise added in different currencies).

Remove the AccountId-element

Filter by a single Id (We have for example 1923-16 as shown in Figure 11).

Change WebsiteId-element so that it holds the correct name for your store. In this case, the demo data is using a store named AllisonNav.

Having done the above you can hit the “Send request” and get a result looking like this:


Figure 19: Debugging a Sana-request as shown in Perfion.

Let us take a look at the result shown here:


<Response>

<Result>

<TotalCount>1</TotalCount>

<Product>

<field name="Blocked" value="0" />

<field name="ModifiedDate" value="1/23/2019 2:26:34 PM" />

<field name="Visible" value="1" />

<field name="HasVariants" value="0" />

<field name="HasPrepacks" value="0" />

<field name="HasMaterials" value="0" />

<field name="VariantComponentsCount" value="0" />

<field name="IsCustomerSpecific" value="0" />

<field name="Barcodes" />

<field name="IsOrderable" value="1" />

<field name="NonOrderableReason" />

<field name="TaxPercent" />

<field name="Inventory" value="15" />

<field name="Price" value="799" />

<field name="ListPrice" value="999" />

<field name="Id" value="1923-16" />

<field name="Title" value="Chambord Coffee maker" />

<field name="Title_1031" value="Chambord kaffebereicher" />

<field name="Description" value="CHAMBORD is the true original – ..." />

<field name="Description_1031" value="Der CHAMBORD Kaffeebereiter ..." />

<field name="Perfion__Brand" value="Bodum" />

<Categories />

<Attachments />

<RelatedProducts />

</Product>

</Result>

</Response>

Note first the field named Title. There are two such fields: Title and Title_1031. Since installation of Sana used is set

up to use US English (LCID 1033) as default language localizable fields output in this language will be output using

simply the fieldname, i.e. Title. All other languages (cultures) will be output with the fieldname post fixed by an

underbar followed by the LCID of the language. Here we have Title_1031 and Description_1031 for outputting Title

and Description-fields in German.

Since Id, Title and Description are all known Sana fieldnames, they are just output (and maybe overriding other values

coming from the ERP). However, Brand is not known, so this name is prefixed by Perfion__ before being output.

Finally notice the absence of Image. Images are output as part of the GetProductImages-request, and hereby not part

of the GetProducts-result.

3.2.7 ECommerce Mappings – For Product Categories

Now with product-mappings in place, we are ready to turn our attention to Product Categories or just Categories.

In versions previous to 3.0.1, the Perfion Connector will never use the ERP-system for getting Product Categories, but

always rely on getting them from Perfion. While this is usually the wanted way, since organizing data in some

categorization in Perfion is often easier than doing it in an ERP-system.

From Perfion 3.0.1 you can choose between getting categories either from ERP-System or Perfion using the

SanaCategoriesSource-setting as described in 3.2.3.

This section will assume that you retrieve categories from Perfion and guide you through mapping any categorizing

feature to Sana. In the examples in this section, we use a feature appropriately named SanaWebsite. This feature is

defined as a typical categorizing feature as shown in Figure 20.


Figure 20: The definition of the SanaWebsite-feature, which will be used for categorization in Sana.

When created it can be given a configuration, but this is strictly not needed. In order to assign product to the various

categories it must be added to a Section in the Section Designer in Perfion. When done you can start creating the

wanted structure. Figure 21 below shows a sample structure entered in Perfion:


Figure 21: The categorizer structure entered in SanaWebsite-feature. This feature is to be used for Product Categories in Sana.

In Figure 21, you note a small hierarchy with Coffee Shop as the root node and that it has 3 sub-categories: Brewing,

Accessories and Cups. The Brewing-category is selected, and you can therefore see the two products assigned to

that.

Having categorizing structure in place, we can turn to mappings of these to meet the requirements for Sana.

Figure 22 shows the necessary mappings:

Figure 22: The mappings needed to import Product Categories from Perfion to Sana.

First mapping is the Context-mapping simply tells the connector, that it is the feature SanaWebsite that holds the

Product Categories (in ECommerce API they are called Categories).

The second mapping requires a small bit of explanation. We did not create a configuration for SanaWebsite. If we

had done that, we could have made some feature holding the unique id of each category and, of course, filled it out

appropriately. Instead, we rely on the fact that Perfion numbers all items with a unique integer. To get to that id we do

not simply write id, since that would denote a feature named id. Instead we write .id (dot id) meaning the value of the

attribute id. This is a so-called attribute mapping and these are explained in more detail in Section 4.2.3. Here it is

enough to know that it simply supplies a unique identifier for the Context feature, here SanaWebsite, and hereby can

provide a unique Id for Sana. The second mapping is therefore is marked as a KeyField and mapped to the field

named Id recognized by Sana as the unique id.


The third mapping is also an attribute mapping. The order-attribute contains the position of the item among its

siblings. This means that if you order your categories (that is SanaWebsite-items) in Perfion, the ordering will be

reflected in Sana.

The fourth mapping takes the base value containing the name of each category and map it to the Title-field in Sana.

Note that the SanaWebsite-feature was created as a localizable and hereby contains a name for each language. The

connector automatically makes sure that all appropriate languages (as defined in settings) are sent to Sana.

The result of the Category-mappings can be checked in Sana by

3.2.8 Testing the result – For Product Categories

With the mappings of categories in place, we can now go to the Sana Admin interface and test the result of our effort.

Using the Request XML below:

<Request>

<Operation>GetProductCategories</Operation>

<Params>

<VisibleOnly>1</VisibleOnly>

<WebsiteId>AllisonNav</WebsiteId>

</Params>

</Request>

You should get the following result back containing the 4 categories in the 2-level hierarchy seen in Figure 22.

<Response>

<Result>

<Node>

<field name="Id" value="2587" />

<field name="SortId" value="5" />

<field name="Title" value="Coffee Shop" />


<Node>



<field name="Title" value="Brewing" />

<field name="Title_1031" value="Zubereiten" />


</Node>

<Node>



<field name="Title" value="Accessories" />

<field name="Title_1031" value="Zubehör" />


</Node>

<Node>



<field name="Title" value="Cups" />


</Node>

</Node>

</Result>

</Response>

3.2.9 Using the Perfion API Tool to debug instead

The output from the ECommerce API is not matching exactly matching the Response XML needed by Sana. It has to

be “slightly changed” by the connector, before being passed on to Sana.

As mentioned earlier, however, the ECommerce API is inspired by Sana, so its output can actually to some extend be

used as-is for implementation/debugging purposes. This is not as good, as doing it directly from the Sana Admin


interface, since the final modifications done by the connector are not carried out. But in case you for some reason

does not (yet) have access to Sana Admin, going straight to the ECommerce API can be beneficial, since it can be

done directly in the Perfion Client.

The ECommerce API-manual can guide you to do that. Here in this manual we will just show you how the above

query looks natively within the ECommerce API.

Here is the GetProducts-method that you would need to use in order to fetch a product by its KeyField:

<Execute method="GetProducts" refreshconfiguration="true">

<Parameter id="Channel" value="AllisonNav" />

<Parameter id="Keys" value="1923-16" />

</Execute>

And the result you get from the ECommerce API. with the exact mappings we created in section 3.2.4, looks like this:

<Response>

<Result>

<Channel name="AllisonNav">


<Products>

<Product id="560" ecommerceproduct="1923-16">

<Fields>

<Field name="Id">1923-16</Field>

<Field name="Title" culture="1033">Chambord Coffee maker</Field>

<Field name="Title" culture="1031">Chambord kaffebereicher</Field>

<Field name="Description" culture="1033">CHAMBORD is the true ...</Field>

<Field name="Description" culture="1031">Der CHAMBORD Kaffeebereiter ...</Field>

<Field name="Brand">Bodum</Field>

</Fields>

<Images>

<Image name="Image" perfionname="Image">

<Guid>1c07ad18-d775-475c-9694-be64e8415163</Guid>

<OriginalFileName>1923-16.jpg</OriginalFileName>

<Url>http://localhost:8100/Perfion/Image.aspx?id=1c07ad18-d775-475c-9694-

be64e8415163&format=jpg&size=1024x1024</Url>

</Image>

</Images>

</Product>

</Products>

</Channel>

</Result>

</Response>

The resemblance to a Sana response is striking. The attentive reader will notice, however, the small changes done by

the connector before leading this to Sana as a Sana response. Most notably, we have:

Elements are named and structured slightly different (i.e. element name used is Field as opposed to field)

Culture is in ECommerce API is an attribute named culture, not a postfix to the field name.

The ECommerce API has no notion of a default language so all localizable data is output with a culture.

The prefixing of known Sana names with “Perfion__” is absent in the ECommerce API. You can see that the Field is named Brand and not Perfion__Brand.

The removal of images. In ECommerce API all mappings are output on GetProducts. On the other hand,

images are passed to Sana when Sana calls the GetProductImages-request, not when calling GetProducts.

3.2.10 Done!

Congratulations! Your first very small and simple configuration of the Perfion Connector has been completed.


Figure 23 shows a complete overview of how feature values are carried on using mappings until they end up on the

product detail page in Sana front end:

Figure 23: All the way from the feature value to content on the product detail page.


4. Creating mappings for Sana The ECommerce API manual describes all the possibilities for constructing mappings to control the output from the

ECommerce API. The results from the ECommerce API, however, needs some tweaking, however, and not

everything that can be done in the ECommerce API is supported by Sana, although much is.

Instead of walking through all constructs of the ECommerce API (which can be found in the manual for that) this

chapter looks at constructing the outputs supported by Sana. This would be:

Fields

Images

Attachments

Related Products

Related Categories

This chapter focuses solely on the Product entity, but will in a table in each section note whether or not this construct

is supported for Categories and Variants also.

Mapping to fields - Output Kind KeyField In chapter 2 we already used this mapping.

Field - Output Kind Field What can be output Supports Supported Entities

Features Attributes Literals

Multi value features Localizable features Merging of features

ProductCategory Product Variant

Sample Data

Sample Mappings

Sample output

<Response>

<Result>


<Product>



<field name="Id" value="1923-16" />

</Product>

</Result>

</Response>

Table 6: Summary of a field being output using Output Kind KeyField

The KeyField-mapping serves one very important purpose. It tells the ECommerce API what feature holds the unique

Id used for the entity (Here Product). This is extremely important to the connector since it takes Id from the result

coming from the ERP-system and fetches all products with exactly that Id. Without a Keyfield the connector has no

idea how to find products in Perfion by some Id.


Mapping to fields - Output Kind Field We have already seen simple examples of this.

Field - Output Kind Field What can be output Supports Supported Entities




Sample Data

Sample Mappings

Sample output

<Response>

<Result>


<Product>





<field name="Description" value="CHAMBORD is the true original – ..." />



<field name="Perfion__UniquePerfionId" value="560" />

<field name="Perfion__NoImageText" value="Photographer on his way" />

<field name="Perfion__MultiValue" value="Value A
Value B
Value C" />

<field name="Perfion__MultiValueDashSeparated" value="Value A-Value B-Value C" />

<field name="Perfion__MultiValueUnorderedList" value="<li>Value

A</li><li>Value B</li><li>Value C</li>" />

</Product>

</Result>

</Response>

Table 7: Summary of fields being output using Output Kind Field

It is worth noting that also dates, numbers in Perfion can be output as well as strings (not shown in Table 7).

The following sub sections walks through all the mappings showed in Table 7.

4.2.1 Localizable features

Both GroupName and Description-features are localizable. This means that the ones not being default language is

output using the appropriate LCID.

Since the field names they are mapped to, Title and Description, respectively, are known names to Sana they are

output as is, i.e. with no “Perfion__”-prefix.


4.2.2 Non-localizable features

BrandName is not a localizable feature, so it is simply output as Perfion_Brand without any prefixed LCID. It is,

however prefixed by “Perfion__”, since it is not a field name known to Sana.

4.2.3 Attributes

Features likely are 99% of what is mapped from Perfion, but it is possible to output other data. The .id-designation

means output the attribute .id for that item (here the product with base value 1923-16). The available attributes can be

found in the Perfion API-documentation, and it is simply the attributes available for each Product/Category returned by

the Perfion API.

Here we simply output the Id of the products in a field named UniquePerfionId. It is prefixed with “Perfion__” for the

usual reason.

Outputting attributes has no notion of localizability and cannot be multi values.

4.2.4 Literals

A literal is another example of something output not coming from a feature. It is simple a constant value, that is output

as-is to a field. A literal is recognized by having its value within quotes. The quotes are (obviously) not transported to

Sana, only the characters between them are.

In Sana, this can be useful to output the field “Visible” as a constant saying 1 as we saw for categories in section

3.2.7.

Outputting constants has no notion of localizability and multi values.

4.2.5 Multi values

A multi value in Perfion is simply a feature that can hold multiple values at the same time. In Table 7 we indeed see in

the sample data that the feature MultiValue indeed holds 3 values: Value A, Value B and Value C.

If no expression is specified as part of the Output Kind, the Sana Connector outputs such multiple values separated

by Carriage return/Line feeds. This works for Sana when for example doing searches and facets on the feature. For

example doing a facet on multi value will find our product when drilling down to either “Value A”, “Value B” or “Value

C”.

Looking at the 3 mappings for the feature MultiValue it is the first mapping (mapped to a field of the same name) that

simply generates an output where a carriage return is separating its values. Note that the values are encoded, so they

are a bit annoying to read in the Xml-output.

The next MultiValue-mapping shows a different approach to the multiple values. Here a so-called expression is used

to tell the ECommerce API how you want the multiple values output. Notice how the expression is supplied in

parenthesis as part of the output kind. Sort of like a parameter to a method. The expression

@FormatMultiValues({Value}|-) outputs the multiple values with a dash between them.

Note that not only multi values can benefit from expressions. See the Perfion API manual for more possibilities than

the FormatMultiValues-expression.

The final example outputting the Multi Value feature is also using an expression. This expression outputs the multiple

values as you would output list items in html, i.e. as <li>(value)</li>. This is useful if the Sana field is rendered

straight on the front end (but does not work if it is used as a facet).

Note: At the time of writing, there is an error in the Perfion API when it handles non-localizable expressions. When

doing that it outputs them as if they were localizable (one for each language asked for). Since the Sana Connector is

relying on the ECommerce API and since that again is relying on the Perfion API to have expressions resolved, the

same issue is here. It should not matter a lot, since the output is the same for all languages asked for in the query.


4.2.6 Fixed expressions

Mainly for legacy reasons, the ECommerce API and hereby also the Perfion Connector, allows you to map what we

called fixed expressions (not to be confused with expressions as described in Section 4.2.5). Currently there is only

one fixed expression and it is named $GetAll().

This fixed expression outputs the entire entity Feature- and Data-nodes as returned from the Perfion API.

The mapping can be created like shown in

Figure 24: Here the @GetAll() fixed expression is mapped to a field named NativePerfionData in Sana.

This means that the following “chunk of data” will be output for that field.


Figure 25: The output of the @GetAll() fixed expressions for some product. Note that Both the Features- and Data-elements in the Xml has been shortened quite a lot for brevity.

Most likely, you will not need this fixed expression in your implementation, but in previous versions of the Perfion

Connector (both 1.0 and 2.0) data on this form was available, so it is kept for backwards compatibility.

Mapping to fields - Using a Wild Card-mapping This kind of mapping was introduced in the ECommerce API in Perfion 4.5.52 and can be utilized when using the

connector. The idea is simple. Many mappings on products are simply taking the value of some feature, mapping it to

a field using the same name. That is fine unless you have many such mappings. Some installations could easily have

over 100 even 1000 mappings created like this.

This is where the wild card-mapping comes in. It simply “auto maps” all features from something we call a view in

Perfion. Default the view used by the ECommerce API is the WebDetail-view.


To control which features there are in a view, go to Features-section. Here you should find the base feature used for

products, usually named Product right-click that and pick Edit configuration. This brings up the list of all features

configured in Product. Now click the right-most button named Web and 3 columns are added, one which is the

WebDetail-column. If you got everything right, you end up something like the window shown in Figure 26:

Figure 26: The configured features on a product. Note that 9 features have been checked for the WebDetail-column, meaning that they are part of the WebDetail view.

Having done that go to your list of products picking that view from the view-selector. This will exactly show 10

features: The 9 features picked plus the base feature. These are shown as sample data in Table 8:


Field - Output Kind Field – Wild card mapping What can be output Supports Supported Entities




Sample Data

Sample Mappings

Sample output

<Response>

<Result>


<Product>





<field name="Description" value="CHAMBORD is the true original ..." />



<field name="Perfion__UniquePerfionId" value="560" />

<field name="Perfion__NoImageText" value="Photographer on his way" />

<field name="Perfion__MultiValue" value="Value A
Value B
Value C" />

<field name="Perfion__DiameterCM" value="7.5" />

<field name="Perfion__DishwasherSafe" value="Yes" />

<field name="Perfion__DishwasherSafe_1031" value="Ja" />

<field name="Perfion__HeightCM" value="25.3" />

<field name="Perfion__ItemName" value="Chambord Coffee maker, 3 cup, 0.35 l, " />

<field name="Perfion__ItemName_1031" value="Chambord Coffee maker, 3 cup, 0.35 l, " />

<field name="Perfion__Material" value="Stainless Steel" />

<field name="Perfion__Material_1031" value="Edelstahl" />

<field name="Perfion__NoOfCups" value="4" />

<field name="Perfion__VolumeL" value="0.35" />

<field name="Perfion__WidthCM" value="19.3" />

<field name="Perfion__MultiValueDashSeparated" value="Value A-Value B-Value C" />

<field name="Perfion__MultiValueUnorderedList" value="<li>Value

A</li><li>Value B</li><li>Value C</li>" />

</Product>

</Result>

</Response>

Table 8: Summary of fields being output using the wild card mapping

The fields output in Table 8 can be directly compared with the fields output in Table 7. In Table 8, fields added due to

the added wild card mapping are shown in italic.

Counting these fields does not count up to nine but only up to eight (remember not to count localizable fields more

than once). The feature named GroupName, although checked in Figure 26 does not appear in the list of output fields.

The reason is simple. That feature already had an explicit mapping (to a field named Title, see Table 7) so it is not

being repeated by the wild card-feature.

If you want to use another view than WebDetail for this feature, you can modify the context node from the current

Product to for example Product/Item. This would pick the view named Item instead. For more info on picking view, see

the ECommerce API manual.


To summarize the wild card-mapping:

The wild card mapping outputs all features checked for the appropriate view (WebDetail

is default) as fields having the exact same names as their corresponding features.

Exceptions are features that already has an explicit mapping regardless of what output

kind is used for that explicit mapping.

Here is just a short FAQ regarding the wild card-mapping:

Question: What if I in my view have checked an Image- or File-features?

Answer: Then these will be output as fields, which is rather useless. If you do not want these

features mapped, uncheck them from the view. If you do want them mapped, but to be output as

Images and Attachments, respectively, make explicit mappings for them (you can keep them

checked or not in the view, since they are not included as fields anyway).

Question: I have many features I need mapped, but some of them need to be given other

names than their feature counterpart?

Answer: You have to create an explicit mapping for each feature you want to output with a

different field name. You can choose to rename the feature to suit your needs, but then you will

also change the name in the Perfion API output, which may or may not be desirable.

Question: I have checked features in my view, which I do not want output as fields. What can I

do?

Answer: You have to create explicit mappings for these picking appropriate output kinds (and

names) for each.

Mapping to images In chapter 2, we have already seen a simple example of an image mapping. Image is reckoned by Sana as a known

field holding images, so in order to map an image feature in Perfion you have to map it to precisely Image and make

sure that Output Kind is set to Image.


Image What can be output Supports Supported Entities


Multi value features Localizable features (only partly) Merging of features


Sample Data

Sample Mappings

Sample output (from the GetProductImages request) – Connector Version 3.0.1 and below

<Response>

<Result>

<ProductImage>

<field name="ProductId" value="1923-16" />

<field name="VariantId" value="" />

<field name="ImageName" value="1c07ad18-d775-475c-9694-be64e8415163.jpg" />

</ProductImage>

<ProductImage>



<field name="ImageName" value="144b5e36-0ba2-4dc8-8e66-b88058ecea29.jpg" />

</ProductImage>

<ProductImage>



<field name="ImageName" value="6abf4cec-1a0b-4558-9a2b-04a9f359460c.jpg" />

</ProductImage>

</Result>

</Response>

Sample output (from the GetProductImages request) – Connector Version 3.0.2 and above

<Response>

<Result>

<ProductImage>



<field name="ImageName" value="1c07ad18-d775-475c-9694-be64e8415163__MainImage.jpg" />

</ProductImage>

<ProductImage>



<field name="ImageName" value="144b5e36-0ba2-4dc8-8e66-b88058ecea29__CoffeeCup.jpg" />

</ProductImage>

<ProductImage>



<field name="ImageName" value="6abf4cec-1a0b-4558-9a2b-04a9f359460c__CoffeeTable.jpg" />

</ProductImage>

</Result>

</Response>

Table 9: Using Output Kind Image to output images. Note the two different results depending on connector version. Note further: Sana request used here is GetProductImages, not GetProducts, which does not return images.


In the example in Table 9, we see two image mappings: One from the feature Image (holding one image for our

sample product) and one for the feature imgDbLifeStyle, which is holding 2 images in our sample product.

The Image Output Kind supports merging of features. This means, that if you make multiple mappings using such an

Output Kind, and you map them to same named output (here both mappings map to Image) then all values for all

these features will be output as one construct. In the example in Table 9, we see that 3 images are output: 1 from

Image and 2 from imgDbLifeStyle. In the Response Xml, you can’t see which ProductImage-element comes from

which feature, but you can in the “corresponding” Result Xml from the ECommerce API.

Note that the most used Output Kind Field does not support merging of features.

The images are output in the same order as their mappings, so the one image in Image will be output before the two

images in imgDbLifeStyle. Within a feature, images are output as done by the Perfion API. It is configurable in Perfion

on a feature in order its values should be output. See Perfion API manual for more information on this.

The Connector does support localizable image features to some extent. Since Sana has no notion of localizable

images, the connector simply outputs all images regardless of which language they belong to in Sana. This is hard to

use for anything, especially since you cannot see on an image to which language it belongs.

4.4.1 Extra data encoded in ImageName-element (Connector Version 3.0.2 and later)

From connector version 3.0.2 the Image Names returned to Sana does not only contain the GUID for the image

(needed by Perfion to later retrieve the image as part of the GetProductImageFile-call).

The culture (if any) together with the file name are “encoded” into the ImageName. This encoding is done exactly the

same way as it has always been done for attachments and is described in section 4.5.1.

4.4.2 A note on the supplied BinaryOutputKind

For those familiar with the various options (various BinaryOutputKinds) for getting images out of the ECommerce API

it should emphasized that with respect to the connector you could pick anything in the mapping. You can do this,

since the connector forces the BinaryOutputKind to suit its needs (it wants urls when GetProductImages is called, but

Embedded when GetProductImageFile is called in order to get the Base64-encoded image). It is recommended,

however, to pick Url (instead of, say, Embedded) since then the debugging queries done straight in the ECommerce

API runs much faster and results are not cluttered with Base64-encoded images.

Mapping to attachments In Perfion Connectors before 3.0.1 it was assumed, that attachments on products were stored in Perfion. From 3.0.1 it

is possible to choose to retrieve attachments from the ERP-system using the SanaAttachmentsSource-setting as

described 3.2.3. This section assumes that you have chosen to store attachments in Perfion.

In Sana, attachments can be both a file stored in Sana and it can simply be a url pointing to something. In Perfion,

files and “urls” are considered two different things: A file you would store in a File-feature while you would store a url

in a string-feature.

The connector handles both kinds of attachments; you just have to set the mapping up slightly different depending on

which type you are working with.

Table 10 gives shows you how it works:


Attachment What can be output Supports Supported Entities


Multi value features Localizable features (only partly) Merging of features


Sample Data

Sample Mapping

Sample output

<Response>

<Result>

<Product>



<Attachments>

<Attachment>

<field name="Type" value="File" />

<field name="Value" value="bb71a5ae-964c-4b34-9436-ea79a1ea65e8_1031_1923-16.pdf" />

<field name="Description" value="1923-16" />

</Attachment>

<Attachment>


<field name="Value" value="08512b3e-6d7c-4ffc-8d16-5a8ba04e02aa_1031_1924-16.pdf" />


</Attachment>

<Attachment>


<field name="Value" value="e72324a1-b497-4531-adf4-8e00e953f4b3_1033_1923-16.pdf" />


</Attachment>

<Attachment>


<field name="Value" value="bc9f0770-5131-44f6-951f-53bb40118cb2_1033_1924-16.pdf" />


</Attachment>

<Attachment>

<field name="Type" value="URL" />

<field name="Value" value="http://www.bodum.com" />

<field name="Description" value="www.bodum.com" />

</Attachment>

</Attachments>

</Product>

</Result>

</Response>

Table 10: Using Output Kind Attachment for outputting attachments

Attachments generally work the same way as images. They do support multi values, merging of features and

localizable features the same way as images do.

As seen in Table 10, we have here our product having both some manuals in the feature InstructionsPDF that is a

localizable File-feature and a link to the manufacturer website in a simple non-localizable string feature named

ManufacturerWebsite. Note the slight differences in mappings. The File-feature uses output kind Attachment(Url),

since this is the Output Kind used to output file-features in the ECommerce API. The string-feature, however, is output


as Output Kind Url, since this tells the ECommerce API to interpret its value as a url and output it as such (basically it

checks if it has a http:// or https:// and if not it adds it, as done with www.bodum.dk in the example).

Both features have their ECommerceTo set to the same thing, Attachment, so they both end up in Sana as

attachments.

As can be seen in the result for the product 1923-16, first we have four instruction manuals output (2 for each of the

two languages as we will see soon) as Type File followed by a single attachment of type URL.

4.5.1 Attachments from File features and localizability

One thing worth mentioning regarding using localizable File-features: While localizable images are output with no way

of distinguishing which image belongs to which culture/language, the file name output for attachments has some extra

information encoded into it.

As can be seen in Table 10 it is output in the xml-element named Value and is constructed of three different parts:

<Guid>_<Culture Id>_<File name with extension>

So taking the first attachment in Table 10 looking like this:

bb71a5ae-964c-4b34-9436-ea79a1ea65e8_1031_1923-16.pdf

This “encoded file name” can be divided into the following 3 sub parts:

Guid: bb71a5ae-964c-4b34-9436-ea79a1ea65e8

Culture Id: 1031

File name: 1923-16.pdf

Therefore, this attachment has the file name 1923-16.pdf for the German culture, and it is being recognized in Perfion

with the unique id bb71a5ae-964c-4b34-9436-ea79a1ea65e8.

Sana does not utilize this in the standard installation, but can (likely) be customized utilizing this. The standard Sana

simply shows all attachments available on the product (ignoring the encoded culture and filename).

Important note regarding the File name-part: If you are utilizing the File name-part you should now, that these file

names are not necessarily unique in Perfion. The example in Table 10 shows it. Here 1923-16.pdf is used twice.

Therefore, uniqueness, if needed, must be ensured using some other mechanism. In Perfion, the Guid ensures it.

Mapping to related products In previous versions to 3.0.1 the connector always assumed that product were related in Perfion rather than in the

ERP-system. In fact, any relations returned by the ERP-system was thrown away by Perfion.

From Connector 3.0.1 you can choose whether you want to fetch related products from Perfion or from ERP-system,

by using the SanaRelatedProductsSource-setting described in section 3.2.3.

In this section we assume, that you have chosen to relate you products in Perfion.

In Perfion, a product can indeed be related to other products. In fact, you can make as many relations as you would

like, representing different kinds of relations. Two products could be considered related if they are reasonably similar,

for example two coffee brewers. They could also be considered related because one is an accessory suitable for the

other. Alternatively, maybe a product is related to all its spare parts. Any such relations can be passed on to Sana.

http://www.bodum.dk/


Note that in Perfion relations are unidirectional. This means that even though Product A is related to Product B, it

does not necessarily mean that Product B is related to Product A.

Related Product What can be output Supports Supported Entities




Sample Data

Sample Mapping

Sample output

<Response>

<Result>


<Product>


<RelatedProducts>

<RelatedProduct id="DFGR1181" type="1" />



</RelatedProducts>

</Product>

</Result>

</Response>

Table 11: Using Output Kind RelatedProduct for outputting related products.

As can be seem from Table 11 Perfion has a feature named Accessories containing exactly accessories for the

various products. For our coffee maker in the sample data, it contains three such accessories (other products).

When outputting a related product to Sana, you need to supply a type of related product since Sana can operate with

different types and handle them differently. In order to do add a type, you write it in parenthesis in the ECommerce

To-value. As can be seen in Table 11 there is a ‘1’ in the example, so this ‘1’ gets outputted as the type of the related

products coming from that mapping, that is, coming from the Accessories-feature. Consult the Sana documentation

for information on this type-attribute on related products.

If no type is supplied, the Perfion Connector will automatically insert a type of ‘1’.

Mapping to related categories As noted in section 3.2.7 you can from connector 3.0.1 choose to get your product categories from ERP-system

instead of Perfion. If you do that, you will not need to read this section since it described how you output your Perfion

related categories on your products.

In Perfion, we have, in section 3.2.7, placed products in categories (or to be more precise in a categorizing feature

named SanaWebsite). In order to tell Sana in which product category (or which product categories) a product belong

we need to create a mapping producing that information. Table 12 shows the details on how such a mapping can be

created:


Related Category What can be output Supports Supported Entities




Sample Data

Sample Mapping

Sample output

<Response>

<Result>


<Product>


<Categories>

<Id>2483</Id>

</Categories>

</Product>

</Result>

</Response>

Table 12: Using Output Kind RelatedCategory for outputting categories

As the result in Table 12 shows, categories are output with their ids. As you remember from Section 3.2.7, as the

unique Id (The KeyField) we chose the id-attribute of the items used for category (which are items of type

SanaWebsite). As can be seen from the sample output in Table 12 the id of Brewing must be 2483.

Note that it is perfectly okay to have the same product placed in multiple categories. It is also perfectly legal to have a

product, which is in no category.


5. Customizing Sana When customizing Sana, often it is necessary to have slightly more information coming from ERP-System or maybe

from the Add-On. The following sections will describe some extra information that can come from the Perfion AddOn

that might be useful when customizing Sana.

Decorating Fields using attributes In Sana a Field has a value. We saw in section 4.2 how a Field could come from various sources, but it all ends up

with something like this being output to Sana:


The above example is taken from Table 8 page 40.

Now suppose that we have some extra information attached to that information, that this machine can brew up to 4

cups. Let us say that some machines brew bigger cups than others as suggested in below:

Figure 27: Here we have added a cup size that contains the size of the cups brewed.

This information can, of course, be parsed to Sana as another field:


<field name="Perfion__CupSize" value="Medium" />

That would just work as expected.

In some cases, however, you are not after yet another field to display on the Sana-site, but rather after some

customization made on the Sana-side. Therefore, you are after some way of passing the information to Sana, without

creating another field.

This extra-information can be utilized on Sana for various options, which are unknown for us here at Perfion.

In the 3.0 connector, you can achieve that passing of data by passing an attribute to the field-element as shown in

Table 13:


Attributes What can be output Supports Supported Entities


Multi value features Localizable features (See note) Merging of features


Sample Data

Sample Mapping

Sample output

<Response>

<Result>


<Product>


<field name="Perfion__NoOfCups" value="4" type="Number" size="Medium" />

<field name="Perfion__Volume" value="0.35" type="Number" unit="l" /> </Product>

</Result>

</Response>

Table 13: Using Output Kind Attribute to decorate field-elements with extra-information.

As can be seen from Table 13, we first use Output Kind Attribute to output the value of the feature CupSize to the

attribute size on the field NoOfCups. Indeed the result is that the field-element for Perfion__NoOfCups is added a

size-attribute being given the value Medium.

The next example is utilizing a feature introduced in Perfion 4.5 2019 R2, namely being able to output an attribute on

a feature. In the example, we output the unit-attribute from the VolumeL-feature as an attribute named unit on the

Volume-Field. Indeed we get a unit containing an “l” (small letter L), which is the abbreviation for liter and is the unit

for the VolumeL-feature. All attributes on Feature-elements from the Perfion API result can be output using this. See

Perfion API-manual on which attributes you can output in addition to unit.

Important: The above example combines the non-localizable feature VolumeL with the localizable attribute unit. This

is generally not a good idea, since you only get the unit output in the default language (here English). The best

solution is to make the VolumeL-feature localizable, meaning that you need to type the same value into that feature

for all languages. As a rule: All data involved should all be either localizable or not localizable. Note that that unit on a

feature is localizable, whether or not the feature is it or not. Combining localizable data with non-localizable data may

not give the wanted result (above you only get the English unit, not the unit in other languages). The ECommerce API-

manual will give you more information on how such data is output in case you combine localizable data with a non-

localizable data.

In Table 13, we have made an explicit mapping of both NoOfCups- and VolumeL-features. This is not necessary for

decorating it with one or more attributes. Fields made using the wild card mapping work just as well.


Grouping information in GetEntityFields This feature requires Connector 3.0.1 and Perfion 4.5 2019 R2

Using the Sana Standard there is no way to pass groups of fields and have Sana react on that. A field is simply a

Field.

The Perfion connector, however, add some more information to this call that can be utilized when customizing Sana.

In Perfion, two constructs help group features:

View: A feature can be in 0 (zero) or more views. Perfion has 14 such views.

A feature can be in a Top View Group and/or in a View Group (and in an Information Group which cannot be sent to Sana). Perfion allows any number of groups to be created.


Sample Groups

Sample Feature

Sample output <?xml version="1.0" encoding="utf-8"?>

<Response>

<Result>



...

<Field>

<field name="Name" value="Perfion__CountryOfOrigin" />

<field name="Caption" value="Country Of Origin" />

<field name="Caption_1031" value="Ursprungsland" />

<field name="Caption_1030" value="Oprindelsesland" />

<field name="Caption_1043" value=" Land van herkomst" />

<field name="Type" value="String" />

<field name="Perfion__Views" value="Item,WebDetail,Variant" />

<field name="Perfion__GroupId" value="f99de14c-ea4c-4415-adf3-96fe03e73247" />

<field name="Perfion__GroupCaption_1030" value="Marketing" />


<field name="Perfion__GroupCaption" value="Marketing" />

<field name="Perfion__GroupCaption_1043" value="Afzet" />

<field name="Perfion__SubgroupId" value="55b92e43-ccad-46c4-9276-29971023644e" />

<field name="Perfion__SubgroupCaption_1030" value="Oprindelse" />

<field name="Perfion__SubgroupCaption_1031" value="Ursprung" />

<field name="Perfion__SubgroupCaption" value="Origin" />

<field name="Perfion__SubgroupCaption_1043" value="Oorsprong" />

</Field>

...

<Result>

<Response>


Table 14 shows the Feature Manufacturer, which Views it is assigned to in the configuration of Product, and which

Groups it is assigned to. Finally it shows how all this is output for the feature as part of the result of a GetEntityFields-

call.

GetEntityFields Sample Views


Sample Groups

Sample Feature


<Response>

<Result>


...

<Field>


















</Field>

...

<Result>

<Response>

Table 14: GetEntityFields-method returns information on Views and Groups from Perfion.


As can be seen in the Sample Views, we have 3 Top View Groups and 2 View Groups. They can be considered

groups and subgroups, respectively and are output as such. In addition, we see that the feature CountryOfOrigin is

assigned the Top View Group Marketing and the View Group Origin. In the output we see that the field

Perfion__GroupId is assigned its unique id and that we for each lcid outputs its captions in fields named

Perfion__GroupCaption. Same goes for the View Group which is called a sub group.

Note that it is possible for a feature to have a Subgroup without having a group.

The views are different. We see in


Sample Groups

Sample Feature


<Response>

<Result>


...

<Field>


















</Field>

...

<Result>

<Response>


Table 14 that the CountryOfOrigin-feature in the Products-configuration is assigned to the views Item, Variant and

WebDetail. These names are fixed in Perfion and in the Sana result output exactly these names in a comma-

separated list in the field Perfion__Views.

One use in Sana of these fields could be to use two views to decide whether a Field is on the list- and detail-pages,

respectively. The Views WebList and WebDetail seem obvious choices for two such views, although any two views

would work.

Note: See the ECommerce-Manual to see the exact names of all 14 available views.


6. Setting up variants The Sana Connector completely relies on the ECommerce API for setting up variants. So please consult the

ECommerce API manual for setting up variants.

When it comes to setting up variants for use by a Sana-shop the following should be noted:

1. All variants created in Perfion must also exist in ERP-system. Otherwise, it would be impossible to put

on order on such a variant.

2. A KeyField-mapping on the Variant entity that maps the feature that holds the unique identifier for each

variant and maps that to a Field named Id in Sana. This must be done on variants in the exactly the same way as it is done for products. Note that it is ok that another feature holds that identifier on Variants than it is

on product. Usually, though, it will be the same feature.

3. Note that in some ERP-systems, variants are only in one dimension. Let us say you have a cup that comes in 3 sizes and 4 colors. This gives a total of 3 x 4 = 12 variants of that cup. Some ERP systems only supporting variants in one dimension will hold these variants in one big list. However, having variants logically grouped by their dimensions gives the user a much better experience. This is called multiple dimensions and is supported by both Sana and Perfion. How variants in multiple dimensions is set up in Perfion, is described in the ECommerce API manual. When it comes to the Sana Connector it should be noted that it is OK to define these variant dimensions in Perfion, despite the fact that they may or may not be in the ERP-system.

Assuming the chapter on setting up variants in the ECommerce API has been studied, this chapter from here shows

an example where variants are set up in Perfion. For details regarding any “ECommerce specific” type mentioned,

please consult the ECommerce API manual.

Figure 28 show the Bodum Bistro-product that we want to also have in Perfion.

Figure 28: The product with variants in the ERP-system.


Note from the figure that the unique id for the product is BODUM BISTRO. Note further that this product has 6

variants (with ids 11581B, 11582B, 11591B etc.). We can also tell that these variants seem to vary at least on their

size, suggested by their title. Furthermore, since this title has the same size listed twice, it seems likely that there is

another variant dimension.

The corresponding items in Perfion could be made as shown in Figure 29:

Figure 29: The same product showing the same variants in Perfion with the few additions needed to support variants.

In Figure 29, we see that the base value for variants indeed matches the Id from the ERP-system. Then we have a

Color-feature and a VolumeL-feature containing values on the variant

Settings In order to enable variant handling a single setting must be set to true:

Figure 30: The setting VariantSupportEnabled that enables variants. Important: Enabling this will make the connector distinguish between items (in Perfion) that are Products, items that

are variants and items that are neither products not variants. This means, that all products must be given the value

Product in a feature named ECommerceType. This must be done for all products, also products that do not have

variants.

Mappings As everything in the ECommerce API which feature that must hold the whether an item is a Product or a Variant is

controlled by a mapping. Therefore, you can pick any name you want. The mappings shown in Figure 31 will take our

variants from the ERP-System to Sana:


Figure 31: The mappings created to support Variants in one dimension for our cups.

The mappings shown above does the following (check ECommerce API manual for more details):

ECommerceType-feature is given the Output Kind ECommerceType. This tells the connector (or more

precise the ECommerce API), that this feature holds either the value Product or Variant (or blank) describing

what entity the item in Perfion represents.

Note: This mapping put on the Product entity, but must also be filled out on variants.

ECommerceVariantOfProduct-feature is given the Output Kind VariantOfProduct and the entity Variant.

This tells the connector that this feature for each Variant holds the Id of the product. In this case, it holds the

value of the Value-feature. In Figure 29 we indeed have, that all variants contains the value BODUM

BISTRO pointing to their product.

Note: In Figure 29, this value is set on all variants. It could as well have been set on the product, and

inherited on all variants. For the connector there is no difference.

Value-feature is then chosen as the KeyField. As for products, variants must have a KeyField matching the

Ids from the ERP-System.

Finally, we have 4 features: ItemName, Color, VolumeL and Image being mapped on the Variant. These

are not telling the ECommerce API anything, except that these contain information that needs to be

transported to Sana.

A general note: Figure 29 shows that some of the feature-values are coming from their parent-nodes (using

inheritance) and others are assigned “directly” on each variant. You can do what you prefer. The connector works with

both.

With the above mappings in place we can test the it on the Sana front end. The result is shown in Figure 32:


Figure 32: The resulting product on the Sana front end. Notice how the variants are in one dimension.

Since we in Perfion have information regarding multiple dimensions we might as well take advantage of the. It

requires only a single new mapping:

Figure 33: In order to support variants in multiple dimensions, the mapping of the feature ECommerceVariantDimensions is added.

This tells the connector (ECommerce API) that a feature named ECommerceVariantDimensions is on products, and

that it will contain the name of all features on Variants that contains the dimensions. For our cups it would be the

Color-feature and the VolumeL-feature (captioned Volume (l) in Perfion).

Important: As opposed to the mappings for ECommerceType and ECommerceVariantOfProducts the mapping for

ECommerceVariantDimensions must have it To-value set and it must be set to exactly VariantDimension as shown in


Figure 34. Reason is that in the ECommerce API the Output Kind VariantDimension, as opposed to the other two, is

producing an output, and all output coming from ECommerce API must be named (just as Output Kinds Field, Image

etc.).

This means, that we need to get back to our BODUM BISTRO-product and add the information for the product. This is

done in Figure 34 below:

Figure 34: The feature ECommerceVariantDimensions is here filled out on the product.

The feature ECommerceVariantDimensions is inherited, so the variants get the same value as the product as shown

in the figure. This is not necessary. As long as the feature-names are added to the product, it suffice.

Note that it is possible to mix products with multiple dimensions with products having variants in only 1 dimension with

products not having variants at all.

The result of our efforts can be checked in Sana and is shown in Figure 35:


Figure 35: With the ECommerceVariantDimensions-feature mapped and filled out, the BODUM BISTRO product is now shown with its multiple (two) dimensions: Color and Volume.


7. Creating multiple shops The big new thing in the 3.0 connector is indeed the capability to set up multiple shops.

This feature is part of the in the ECommerce API, so please read the chapter about Channels in the ECommerce API

manual.


8. Debugging the connector and connector setup One of the most powerful ways of debugging your setup in the Perfion Connector is by using the “Debug ERP

request” available in the Sana Admin-interface as described in 3.2.8. This allows you to look at your data as it is

presented to Sana. Do the results given to Sana look correct or not?

If they do not look correct, the 2.0 connector had the option to enable debugging files allowing you to see each step

the connector carries out; which (simplified) consisted of these 5 steps:

1) Call the ERP to obtain result

2) Constructing the query used to call Perfion

3) Call Perfion to obtain result

4) Doing an xsl-transformation on result returned from Perfion

5) Doing an xsl-transformation merging ERP-result with Perfion result

That way each sub-result could be investigated allowing you to get closer to the issue.

This option is no longer available in the 3.0 connector. When enabling Debug-information (See section 3.1) all debug-

information (which is more or less 1:1 with what the 2.0-connector logged in individual files) is logged in the change

log. This makes it slightly harder to get a good overview of what happens.

Figure 36 below shows an example where the “Test connection”-operation is called from Sana:


Figure 36: Information logged by the Perfion Connector for the "TestConnection"-operation.

Debugging the connector using the output in the tracelog.txt, as opposed to using the files output from the 2.0

connector, is more cumbersome.


9. The Image Cache Note: This feature was introduced in connector 3.0.3.

When Sana Requests products, it does so, either because index is being rebuilt or (more often) because some

products are flagged by either the ERP-system or Perfion as “have been updated since last update”.

For updated products Sana will do the following

1) Sana will hereafter call “GetProducts” to retrieve product data

2) Sana will call “GetProductImages” to retrieve any images on these products

3) Finally Sana will for each image returned by GetProductImages call GetProductImageFile to retrieve each individual image.

Usually that will work well. Although for installations with many images and/or many changes to products, this way of

retrieving images will put too much load on Sana. And often this load would be unnecessary, since usually image data

will be rather static while product data is more subject to change. To put it more simple. Let us say you have a product

in you ERP, which also is in Perfion. Let us further say it has 8 images. Changing the title of that product will cause

the images to be shipped (again) to Sana.

This is where the image cache in the connector comes in. It is really not a cache containing images. Rather it is a

cache that remembers which images are sent to Sana (and when) and uses that to decide when a

“GetProductImages”-call comes from Sana whether to return the images to Sana or to drop at least some of them,

since they have not changed since last time Sana asked.

It basically works like this:

1) When Sana calls GetProductImages first time the cache does nothing (since it is empty)

2) When Sana call GetProductImageFile the cache remembers that this image was sent, for some product/variant combination in some Sana Store.

3) When Sana later calls GetProductImages (for example because the product or one of its variants were modified) the images already sent will not be returned. Only modified or added images (not cached yet) will be returned. Hereby Sana avoids unnecessary calls to GetProductImageFile for images already fetched.

Enabling the Image Cache This is simply done in settings. Simply toggle the “Enable Image Cache” on as shown in Figure 37 below:


Figure 37: Enabling the Image Cache in the Perfion Connector

The Image Life Time can be safely set to 0, meaning that an Image will live forever in the cache.

The content in the cache is persisted using the FileSystem-API provided by Sana every 5th minute meaning that the

Image Cache will survive a recycle of IIS or even restart of the server, although content will be up to 5 minutes old.

The Image Cache can be accessed in the Debug Erp-request windows. The connector supports four operations

GetPerfionImageCache, ClearPerfionImageCache, PersistPerfionImageCache and GetPerfionImageCacheFile.

These four operations can simply be called just like any other “native” Sana-operation as shown in Figure 38:


Figure 38: Running a Debug Erp-request querying the Image Cache.

9.1.1 GetPerfionImageCache

The GetPerfionImageCache simply shows the current contents of the cache. It supports two parameters:

- WebsiteId: Here you must supply the name of a SanaStore or a “*” meaning you are interested in all stores.

- ProductIds: This is optional. If you only are interested in a few products, these may be supplied using this

parameter.


A sample query could look like the following:

<Request> <Operation>GetPerfionImageCache</Operation> <Params> <WebsiteId>AllisonNav</WebsiteId> </Params> </Request>

Showing cache content for the WebsiteId “AllisonNav” (all images cached on all products).

If we instead would like to see whether two products numbered “A” and “B” across all websites we would write:

<Request> <Operation>GetPerfionImageCache</Operation> <Params> <WebsiteId>*</WebsiteId> <ProductIds> <ProductId>A</ProductId> <ProductId>B</ProductId> </ProductIds> </Params> </Request>

Notice the * supplied as WebsiteId meaning “All channels”. How the result will look is shown in Section 9.1.3.

9.1.2 ClearPerfionImageCache

The ClearPerfionImageCache operation allows you to delete part of the content of the cache or clear it entirely.

It supports the same two parameters as GetPerfionImageCache:

- WebsiteId: Here you must supply the name of a Website/Sana store or a “*” meaning you want to delete

content across all stores.

- ProductIds: This is optional. Here you may supply supply one or more Ids of products that should be deleted

from cache. If no product ids are supplied the entire cache will be deleted (for all applicable Sana Stores)

The operation returns the deleted image cache entries.

The operation:

<Request> <Operation>ClearPerfionImageCache</Operation> <Params> <WebsiteId>AllisonNav</WebsiteId> </Params> </Request>

Will delete everything cached for AllisonNav. If only one image was cached for that store the result would look like:

<Response> <Result> <Channel name="AllisonNav"> <Images> <Image> <ProductId>1923-16</ProductId> <VariantId></VariantId> <ImageName>144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg</ImageName> </Image> </Images> </Channel> </Result> </Response>


9.1.3 PersistPerfionImageCache

The PersistPerfionImageCache-operation allows you to save the current content of the cache to disc. This is usually

not needed since it is done automatically every 5 minutes as part of any request hitting Sana.

The operation does not take any parameters:

<Request> <Operation>PersistPerfionImageCache</Operation> <Params /> </Request>

Note that an empty Params-element needs to be added, otherwise Sana never responds.

The response will be a simple OK if successful:

<Response> <Result> <PersistPerfionImageCache>OK</PersistPerfionImageCache> </Result> </Response>

9.1.4 GetPerfionImageCacheFile

This method was added in Sana Connector 3.0.4. The Image Cache file could get corrupted meaning that it contained

invalid Xml and would hereby not work. In fact the 3.0.3 connector would stop returning images in GetProductImages.

To avoid this issue three steps were taken:

- If the Connector Failed to load a ImageCache-file it would be backed up and cache was started empty.

- A method named GetPerfionImageCacheFile

This method allows you to check the content of the cached image file. The request here will make a check:

<Request> <Operation>GetPerfionOImageCacheFile</Operation> <Params /> </Request>

And return the following:

<Response> <Result> <FileName>ImageCache.xml</FileName> <FileExists>1</FileExists> <FileSize>3528</FileSize> <TimeReadingFile>0,0010023 s</TimeReadingFile> <ExceptionReadingFile>(None)</ExceptionReadingFile> <TimeParsingFile>0 s</TimeParsingFile> <ExceptionParsingFileContentAsXml>(None)</ExceptionParsingFileContentAsXml> </Result> </Response>

Here you get information on the file, whether it exists, its size and whether it could be read (and an exception if not) and interpreted as Xml and how long this takes.


If you supply the parameter “IncludeContentAsCData” as shown below, it will even show you its content (result not shown). <Request> <Operation>GetPerfionImageCacheFile</Operation> <Params> <IncludeContentAsCData>1</IncludeContentAsCData> <RemoveTimeStamps>1</RemoveTimeStamps> </Params> </Request>

Example Let us take a look at how the Image Cache works. After enabling the cache try the following query (adapted to use an

id of a product in your setup):

<Request> <Operation>GetProductImages</Operation> <Params> <WebsiteId>AllisonNav</WebsiteId> <Filter> <for field="Id"> <Equal>1923-16</Equal> </for> </Filter> </Params> </Request>

This results in the following, since product 1923-16 has 3 images.

<Response> <Result> <ProductImage> <field name="ProductId" value="1923-16" /> <field name="VariantId" value="" /> <field name="ImageName" value="fa1550bb-4f2d-4757-9eaa-52404dcb95a6__1923-16.jpg" /> </ProductImage> <ProductImage> <field name="ProductId" value="1923-16" /> <field name="VariantId" value="" /> <field name="ImageName" value="144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg" /> </ProductImage> <ProductImage> <field name="ProductId" value="1923-16" /> <field name="VariantId" value="" /> <field name="ImageName" value="6abf4cec-1a0b-4558-9a2b-04a9f359460c__french-press-lifestyle.jpg" /> </ProductImage> </Result> </Response>

Remember that GetProductImages does not affect the cache but is only affected by it. Since we started with an empty cache all 3 images are returned to Sana. In order to add an image to cache, we need to call GetProductImageFile. It looks like this:

<Request> <Operation>GetProductImageFile</Operation> <Params> <WebsiteId>AllisonNav</WebsiteId> <ProductId>1923-16</ProductId> <VariantId></VariantId> <ImageName>144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg</ImageName> </Params> </Request>

With an enabled cache this operation will, in addition to return the image, also remember that this image was returned.


Now calling GetProductImages-operation again (in the exact same way as before) we get a different result:

<Response> <Result> <ProductImage> <field name="ProductId" value="1923-16" /> <field name="VariantId" value="" /> <field name="ImageName" value="fa1550bb-4f2d-4757-9eaa-52404dcb95a6__1923-16.jpg" /> </ProductImage>  <ProductImage> <field name="ProductId" value="1923-16" /> <field name="VariantId" value="" /> <field name="ImageName" value="6abf4cec-1a0b-4558-9a2b-04a9f359460c__french-press-lifestyle.jpg" /> </ProductImage> </Result> </Response>

Notice how the cached image will be commented out in the result. With an image in the cache you can use GetPerfionImageCache-operation to check that indeed an image is in the cache. It gives the following result:

<Response> <Result>             <Channel name="AllisonNav"> <Images> <Image datetime="2019-08-13T13:48:51"> <ProductId>1923-16</ProductId> <VariantId></VariantId> <ImageName>144b5e36-0ba2-4dc8-8e66-b88058ecea29__coffee-beans-lifestyle.jpg</ImageName> </Image> </Images> </Channel> </Result> </Response>

Troubleshooting If you for some reason thinks that the Image Cache has forgotten (or lost) it’s content. It may be due to a corrupt

ImageCache-file. If you run “on-premise” you can check the folder ..\@data\packages-data\Perfion and see

whether there are any backup-files. Usually they will contain invalid xml and have therefore been backed up and a

fresh empty cache file has been created in its place.

Figure 39: The package-folder for Perfion here contains two backup files and the currently used Image Cache.


In case a backup is taken often, please contact Sana Support or Perfion Support.

Final remark regarding disabling the cache When cache is disabled it first and foremost mean two things:

1) No more images are cached. This means that calls to GetProductImageFile-operations will not add anything to cache.

2) Images will not be removed from GetProductImages due to an image being in cache.

What, however, is not affected is the persisted Image Cache-file. It will, for example, not be emptied or deleted,

meaning that you can disable the cache and re-enable it without losing its content. The GetPerfionImage-operation

will also still work on a disabled cache showing its now rather static content. Even PersistPerfionImageCache-

operation will work.

Documents

Perfion/Sana Connector 3 Connector 3.0.pdf · This document is about the 3.0 connector or rather connectors, because there are two of those: One for Sana Commerce 9.1.4-9.2.x and