Sana Connector 3.0 - Configuration

Configuration in Sana

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.

Open

Figure 1: 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.

Web Service Timeout (Available from version 3.0.7):  Here you can change how much time you allow the Web Service to answer the ECommerce API methods called by the Sana Connector. The default timeout of 100 seconds, which is also the timeout used by older versions of the connector. Generally 100 seconds should be long time enough so this should only rarely be changed to allow more time.

User and Password (Available from version 3.1.5): If Perfion API Service Authentication is enabled on the Perfion API, it will require you to supply the user name and password for a valid user. These can be supplied here.

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.

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.

Output Images as Fields on Products and Variants: Introduced in Connector version 3.0.8, enabling this setting will make all images mapped in the ECommerce API become output as fields (not images) to Sana.

When enabled Sana will receive the unique guid of all images mapped to Sana as Fields, like shown below where 3 images are shipped to Sana:

      <field name="Perfion__Image" value="f3954283-f7c6-48d9-9ef2-8da589cf852e" />

      <field name="Perfion__Image" value="4da8f0e4-fcbb-47a1-adf1-bc6c50fdbe07" />

      <field name="Perfion__Image" value="58e113b1-10a0-43c9-8343-85a8aad4ed8e" />

As can be seen it is the unique Guid that is sent to Sana as the value of each field.

This is a very special setting reserved for a special custom setup done by Sana. This should be left off in all but these cases.

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

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.

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 2. 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).

Open

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

Table 1 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 2.

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

The next section 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 3.

Setting up Image Transfer

In order to make sure that images are transferred correctly to the frontend, the following steps are required:

• Go to Scheduled Tasks, click “Edit” on Product Image Import

• Ensure that “Import product images from ERP” is enable

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.

Configuration in Perfion

This section will take you through all the necessary steps to make a first simple configuration.

Install ECommerce API

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 5 one of the features, the ECommerce Settings, are shown:

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.

• 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”.

• ECommerce Settings: Here you find the settings needed to set up the Connector. These are the ones shown in Figure 5.

• 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.

• 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.

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

ECommerce Channels

A Channel is the ECommerce API equivalence of a store (aka website) in Sana. Below in Figure 6 a single channel named “SanaStore” 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.

The name “SanaStore” 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. SanaStore is a demo web site on our demo server.

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 3):

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 8 all settings have been set up correctly (for some demo-setup):

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

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, German and Dutch to Sana (Perfion language name “EN”, “DE” and “NLD”).

Sana does not work with languages but cultures denoted by their LCID (a Language Code Identifier proprietary to Microsoft). In later section 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 Perfion and Sana.

In most installations, Sana runs on UTC time, but that is not always the case, they are actually using “IIS Server Time”. To find Sana timezone, please check what timezone the IIS-server running Sana is using.

The Perfion timezone is defined in the Ecommerce setting “Timezone” (See Ecommerce Documenation). If this setting has not been defined, the timezone of the Perfion database will be used. If your using Perfion version 4.7 or later the database will be in UTC time.

SaneTimeDifference should be set to the time difference between the Sana IIS-Servers timezone and the timezone of the Perfion database. Here are a few examples:

• Perfion runs in Universal Time Coordinated (UTC) – Sana runs also in UTC
  This will be the most common scenario, and in this scenario this setting is redundant and not needed.

• Perfion runs in UTC – Sana Runs in Central European Time (CET)
  SaneTimeDifference should be set to -1, since Coordinated Universal Time is one hour ahead of CET

• Perfion runs in UTC – Sana Runs in Pacific Time (PT)
  SanaTimeDifference should be set to -7, since Coordinated Universal Time is seven hours ahead of UTC.

• Perfion runs in India Standard Time (IST) – Sana Runs in UTC
  SanaTimeDifference should be set to -5.5, since India Standard Time is 5 and a half hours ahead of UTC. Note that you must use a “.” (punctuation mark) as decimal separator.

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:

As can be seen in the figure the database is 2 hours ahead of UTC Time (because it is in Central European Time), so a -2 needs to be put in as time difference. This assumes that Sana runs on UTC, but remember to check the Sana IIS-server time.

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

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 10, 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.

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 2 shows different combinations of templates, captions and units.

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

As can be seen from Table 2, 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.

Setting: TimeZone (requires Perfion 4.7 and later)

If you have Perfion 4.7 or later, the ECommerce API setting TimeZone should be used and set to “utc” (Coordinated Universal Time). This will make the ECommerce API use the exact same time zone as Sana.

When doing this make sure that the setting SanaTimeDifference is either deleted or simply set to 0 since there is no need to “convert” between times in Perfion and Sana.

Setting: SanaDefaultCultureId

As part of how the connector works, the ERP part of Sana tells the web part the LCID of which culture Sana recognizes as the default culture.

The connector picks that culture up, since it tells the web-part of Sana how it can expect xml-results to be formatted, and since the connector also produces XML for the Sana web part, it must adhere to those rules as defined by Sana.

There are two “things” that need to take the default culture into account, when xml is produced for Sana. These are:

1. Field Naming: How localizable fields should be named. Non-default cultures should have the LCID of the culture post fixed, i.e. <field name="Description_1033" value="Some american description" />, if 1033 is not the default culture. For the default culture the localizable field for Description should simply be <field name="Description" value="Einige deutsche Beschreibung" />.

2. Value formatting: How dates and numbers are formatted. Here numbers and dates should be formatted as Microsoft defines "NumberFormat" and "ShortDatePattern", respectively, using the default culture.

In some cases, Sana ERP reports a wrong Culture Id to the web-part of Sana, and hereby also the connector. In that case, you can choose to override whatever culture Sana ERP says. To do that, you can set the setting SanaDefaultCultureId to whatever LCID you would like. This will make the Connector produce its Xml using whatever id supplied in SanaDefaultCultureId instead of the one returned by Sana ERP.

In Figure 8 you can see this setting is commented out, since it normally is not necessary to set.

Settings: SanaDefaultCultureId_FieldNaming and SanaDefaultCultureId_ValueFormatting (Requires Connector 3.2.1)

The above described setting, SanaDefaultCultureId, controls both how fields are named and how numeric and date values are formatted. In Connector 3.2.1, however, it is possible to control the culture id used by each of these individually. On rare occasions that is needed.

The two introduced settings are:

1. SanaDefaultCultureId_FieldNaming: As the name implies this setting controls Field Naming.

2. SanaDefaultCultureId_ValueFormatting: As the name implies this setting controls Value Formatting.

If, say, SanaDefaultCultureId_FieldNaming is set, this setting will take precedence over SanaDefaultCultureId that again takes precedence over what Sana ERP tells the connector/Sana web part. Similarly precedence rules applies to SanaDefaultCultureId_ValueFormatting.

Note: The above settings are not shown in Figure 8.

A few more settings are available

There are a few more settings in the ECommerce API than shown above. One of them, VariantSupportEnabled. 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 earlier section, created the “SanaStore” 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.

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

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 3 below for a few examples:

Table 3: 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 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 11 below:

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 12 below found in that database:

The 6 mappings shown in Figure 13 below will map exactly the products with the features shown in Figure 12 to Sana. This section will continue explaining how these 6 mappings work.

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. “Please note that feature names in the “From” column are case sensitive, and must match the feature definition exactly.”

• 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 4^th mapping in Figure 13: 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 13. 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 4 contains a table of all names that the Perfion Connector considers known.

Table 4: 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 12) 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.

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 12. 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.

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 15:

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 8).

• 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:

Let us take a look at the result shown here:

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.

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.

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.

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 20 below shows a sample structure entered in Perfion:

This feature is to be used for Product Categories in Sana.

In Figure 18, you note a small hierarchy with Coffee Shop as the root node and that it has 4 sub-categories: Brewing, Keeping warm, 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 19 shows the necessary mappings:

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. 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

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:

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

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:

And the result you get from the ECommerce API looks like this:

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.

Figure 20 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: