Sana Connector 3.0

Owned by Morten Lindequist Køhler
Last updated: Sept 24, 2024 by Michael Engesgaard
7 min read

Overview

The Perfion Connector 3.0 for Sana is a Sana Add-On which you can acquire in the Apps section of Sana Cloud.

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:

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:

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.

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

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

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

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

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

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

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.

Wild card-mapping

Another benefit of using the ECommerce API is that it 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.

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.

Available in the Sana Store

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

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.

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.

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.

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.

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

Requires connector 3.0.2

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.

Image Names passed to Sana now contains culture and file name

Requires connector 3.0.2

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.

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.

Added option to set timeout for methods calls to the Perfion API

Requires connector 3.0.7

This has been added, although it is rarely needed to be changed from the 100 seconds it is per default.

Changes from 3.0 to 3.1 connector

The introduction of Sana Commerce Cloud required a connector to be written entirely in the .net core framework. This is the reason why the 3.1 connector was introduced. 3.1.1 and 3.1.2 followed quickly, fixing issues introduced as part of the migration to .net core. 3.0.15 and 3.1.2 are functionally equivalent.

Changes from 3.1 to 3.2 connector

Sana Commerce Cloud was moved to .net 8.0.

Possible to put descriptions on attachments

You can now add nice, telling descriptions to Attachments sent to Sana.

Added support for boolean types

You can now transport boolean types from Perfion to Sana without converting them to strings in Sana. Simply create a “tri-state” boolean in Perfion and map it, and the connector will take care of the rest

 

 

Read more: