Sana Connector 2.0 - Configuring

This chapter takes you through all configuration needed in order for the connector to work.

Configuration in Sana

When the Connector is installed it needs to be configured in order for it to reach Perfion. In Sana Admin, go to Tools -> Add-ons and click the “Configure”-button for the “Perfion”-entry in the list. This will bring up the following configuration screen:

Open

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

Enabled: Make sure you have this set to “ON” in order to enable the Perfion Connector. When disabled the Perfion connector will not do anything (besides some internal initialization on first request) but relay all calls directly to the Erp-System connected. It will not touch neither the requests nor the data returned from the Erp-System in Disabled state. Disabling the connector is mainly for debugging purposes.

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

Image Service Url: Here you must type the full URL to the Perfion Image Service. If you output images from Perfion to Sana, this must be supplied in order to retrieve the image bytes. If you do not supply any images from Perfion to Sana this is not needed.

File Service Url: Here you must type the full URL to the Perfion File Service. Used to supply Sana with the binary data of file attachments from Perfion. If attachments of type file is not used, this is not necessary.

Logging: Enabled logging in order to log all calls from Sana, all data fetching and data transformation done by the connector. Note that only calls handled by the connector are logged. The log files can be found in the starter-site in the folder “Configuration/Simple/Debug” (when running Simple-mode. Otherwise change Simple to Advanced).

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 from the ERP without trying to augment the data with data from Perfion. If this setting is on, however, such errors will not stop the connector from going to Perfion. Even if the setting is on the errors are still returned to Sana. Normally this settings is only on during the implementation phase.

Advanced: This should in 99% of all installations be disabled. The connector utilizes xsl-transformations to map data from data returned from the Perfion API to data the way Sana likes them presented. These xsl-transformations are generated automatically by the connector when in simple mode. When in advanced mode, these xsl-transformations can be written manually.

Bottommost the Version of the connector is shown, here 2.0.0. 

Test Connection button simple tests all filled out connections to Perfion using the Web Service URL, Image Service URL and File Service URL.

Configuration in Perfion

Configuration in Perfion is done created some features, some configurations and filling these out with data. From Perfion 4.5.17 there is a “developer option” in Perfion making Perfion auto create the features and configurations needed and auto filling them with data that would work for the standard Perfion Demo database, but would need adjusting to fit almost any other Perfion Database.

Auto create features and configuration

In order to get a starting point, let us start of by auto generating the configuration that would work for the standard demo database:

• Start Perfion and make sure it is version 4.5.17 or later. 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 Sana Features and Data”:

Open

Figure 4: Installing the Sana Features and Configurations needed in Perfion

It is always advised to do a backup before doing operations like this. Asking “Yes” in the “Are you sure”-dialog will start the process and it takes about 5 to 10 seconds depending on your hardware. A message-dialog will show up when done.

When done you have the features and configurations needed to set up the Connector. As mentioned earlier they will be set up matching the Perfion Demo Database, and in all but a few cases (if not all cases) you will need to adjust the settings created.

To see what has been added. First go to “Feature Data”, expand the “String”-features node followed by the “Sana Features”-node. Here you will find 4 selectable features where some needs to be filled out:

• Sana Entity: Here are one entry for each Sana Entity that we support mapping data from Perfion to Sana: Category, Product, Variant and Language Deviation.

• Sana Mapping: Here you find all mappings from Perfion 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, but it is more convenient to edit the mappings through Sana Entity.

• Sana Settings: Here you find the settings needed to set up the Connector.

• Sana Type: This is just a selectable feature that may be added to the configuration of Products, if variant support is needed. More on that later.

Configuring the Connector: Settings

You will see two settings here, but a few more can be added manually if wanted:

• Languages: Here you indicate which languages in Perfion that should be copied to Sana when data is synchronized. In Perfion we work with “Languages” and are 99% of them are taken from the ISO 639-2 standard. The Sana Connector automatically map from the Perfion Language Code to the Sana Culture Id. If you, for some reason, are not satisfied with the Sana Culture Id the Connector associates with some Perfion language this can be overridden.

• SanaTypeFeatureName: This setting is blank when auto created. Blank means that Variant-support is disabled, if you want variant support it can be enabled by writing the name of the feature controlling whether an Item in Perfion (a product) is either a “Product” or a “Variant”. This feature must then be present on all items (that is Products) in Perfion indicating whether it is a product, a variant or neither.

Consider the following products:

Some of the above rows represent a product. For example the first row with Item Number “ONESIZETSHIRT”.

Some of the above rows represents variants of some product. Row 4 and 5 (Item Number TSKYLO001-BLACK-L and TSKYLO001-BLACK-S, respectively) represent variants (in size) of the product in row 1 (Item Number TSKYLO001).

Some rows shown are neither representing a product nor a variant, but are simple there for conveniently structuring and entering data in Perfion.

The Perfion Connector knows which are which by looking at the value of the “SanaType”-feature (assuming that you set the SanaTypeFeatureName-setting to “SanaType”). For products it must be “Product” and for variants it must be “Variant”. So in order to enable variant support using the “SanaType”-feature to distinguish between products and variants you will simply need to write “SanaType” for the setting “SanaTypeFeatureName” (as already done in Figure 5).

So to put it brief: For the connector to support variants and be able to distinguish what is a product and what is a variant you need a feature on all products that is set to “Product” for products, “Variant” for variants and anything else for rows not representing either of the two.

As you can see from Figure 5 a feature named “Sana Type” is already auto created. This features simply needs to be put in the configuration for your products and assigned a value on all products and variants (and left blank on everything else).

• ImageWidth and ImageHeight: This setting is not shown in the figure and not part of the auto created settings. Nevertheless these two settings can be used to control how large images sent to Sana should be when Sana asks for images. If not set ImageWidth and ImageHeight is per default set to 1024 and 800, respectively.

• RelatedProductsDefaultType: This setting controls the default type of related products if not specified on the mapping itself. If not specified, the type is set to 1 meaning “Related Product or accessory”. More on this type can be found in Sana’s documentation on here related products.

Configuring the connector: Entity “Product”

Now let us switch from Setting to Mappings. A mapping is simply two names in two different systems for something that is really the same: What this “something” is called in Perfion and what the same thing is called in Sana. As Perfion is completely customizable, it differs from installation to installation which mappings that are needed. Said simple: By creating mappings you simple tell the connector which data you want copied from Perfion to Sana for each entity.

Go to the “Sana Entity” on “Feature Data” and double click the “Product”-Entity on the right hand side:

This will bring up the Item Editor for that entity. All entities, including “Product”, contains all mappings from Perfion to Sana for that entity.

Let us look at the mappings auto created for “Product”, which will make this a lot less abstract:

Let us look at them from the top.

Product/WebDetail/SanaProductSearch is not really a mapping. It is simple an expression that tells the Connector 3 things (each “thing” separated by a slash):

1. What is the name of the base feature in which products are stored. In this case (the Demoo Database) this feature is called “Product”. In case your installation used another base-feature make sure to change it here.

2. What view should the connector fetch from? (List, Item, WebList, WebDetail etc.) The does only affect the @GetAll()-fixed expression that will be explained later. This can be left as is.

3. Finally it is possible write the name of a filter (that is the name of a value of a Search-feature named SanaSearches) which the connector should apply when fetching products. Since the connector is using the ERP to determine which products to fetch, making a filter for products does rarely make sense. It does, however, makes sense for Categories, since here it is Perfion, which determines which categories to fetch. When auto creating Sana-features a value named “SanaProductSearch” is created and pointed to in the Context-node (this is only autocreated in Perfion Client 4.5.28 or later). That value has an empty query meaning the no products are filtered away per default. 

This mapping is not mapped to anything Sana. Instead “SanaTo” must contain the word “@Context” in order to recognize this “non-mapping”.

Now let us continue with the “real” mappings:

ItemNumber: Here we simply map the content of a Feature named “ItemNumber” to a field named “Id” in Sana. In the demo database that comes with Perfion, the “ItemNumber”-feature holds the unique id of the product and in Sana the field “Id” does exactly the same.

The ItemNumber feature in Perfion must hold the exactly same value as the field holding the unique Id of the product in the attached ERP-system. That way the connector recognizes the products in ERP and can find exactly their data in Perfion. In Microsoft Dynamics NAV this field is called “No.”:

Value: Value is used in Perfion to denote the value of the base feature. In the Demo Database, Value holds the title for each product. Just as the field “Title” does in Sana.

Description: The Description-feature on products is mapped to the description field in Sana.

Brochure: The feature “Brochure” in Perfion is a File-feature meaning that it holds files. These files are mapped to “Attachment” in Sana as can be seen. Note that the type of attachment (in this case a file) is written as parameter. The current connector only supports mapping file-features to file-attachments in Sana, but in a later version it will be possible to ask for a URL-attachment in Sana making the connector build a URL pointing to the “File Web Service” that will retrieve the file once clicked.

WebLink: The feature “WebLink” in Perfion holds a URL. This fits the URL-attachment in Sana.

Note that both Brochure and WebLink causes attachments to be created. It is perfectly okay to have multiple features add to attachments, related products and images.

RelatedProducts: Note that this mapping is commented out using a “#”. If commented in this will output as related products the products found in the “RelatedProducts” feature. This feature is simply a feature in Perfion holding references to other products.

Accessories: This is the same as RelatedProducts. Again we have the content of two features ending up as something (here Related Products) in Sana.

Image: The content of the feature named “Image” will end up as an Image in Sana. In the Perfion Demo database “Image” is a single-value feature. The connector also supports multi value features for which all images will be added to Sana.

It is allowed to map multiple features to Image in Sana. All images on a product will be copied to Sana.

@GetAll(): This is also commented out in the figure. When added this will output the Xml returned from the Perfion API for that concrete product. Both Features and Data-section will be added. Generally this should not be needed, but it is available since Connector versions prior to version 2.0.0 did support getting Perfion Data out there and it may be used. In older versions the information was split on two nodes.

Manufacturer: This is a mapping from the feature named “Manufacturer” to a field named the same in Sana. Since Sana hos no notion of a manufacturer this is a so-called “Custom field” or “Extra field” in Sana. Such field are shown in Sana as “[Perfion] Manufacturer” and internally named as “Perfion__Manufacturer”. Note that it is not allowed to map multiple features in Perfion to the same custom field in Sana.

With the above mapping on products you will get the result showing in figure below:

Configuring the connector: Entity “Variant”

This section is only necessary for you, if your Sana Installation needs to support variants. Otherwise you can safely skip this.

In Sana, variants do not have near as many fields to be filled out as products. Let us take a look at the auto created mappings on variants:

SanaVariant: This mapping must hold the name of the feature that holds the unique Id for that variant in the ERP-system. Let us take a look at a product (an Item) in Microsoft Dynamics NAV:

Note that each variant has a unique “Code”. This code must be mapped to the variants in Perfion. In Perfion it can be modelled like showed in Figure 13, where a feature named SanaVariant holds the Id (i.e. the “Code”):

Note the Sana Variant-feature that holds the unique Id for each variant exactly corresponding to "Code" on variants in MS Dynamics NAV.

You may name the feature as you want, as long as you make sure to map it to “Id” in Sana as shown in Figure 11. The Sana Connector recognizes the “Id” on the Sana Side and uses whatever name put a base value on the mapping.

A short note on Item Number on variants: In the above example we have chosen to have the “Full Id” of the Variant in Item Number, i.e. the Id of the product followed by the Id of the variant separated by a dash. This is not necessary to do that. It is enough to have the Sana Variant-feature holding the “Code”. Some may prefer to leave this blank on variants, for example, which is OK. 

SanaProduct: This feature must hold the name of the Product associated with a variant. In Figure 13 we see that variants MULTI and ORG both point to the product numbered SPALDING. Notice in the figure, that Sana Product is made as an inheritable feature. It is not necessary but a good idea, since you then can set it on all children (variants) in one go.

As SanaVariant this feature may be called whatever you like as long as it maps to its “ProductId” on the Sana side.

SanaVariantTitle: This feature should hold the title (descriptive name) for each variant. These descriptive names are indeed used by Sana to output to the end user, for example in a variant selector. This feature can also be named as you wish, as long as it points to the “Title”-field in Sana.

VariantImage: Sana supports having specific images for variants. This means that you can actually have a picture of a yellow shirt for the yellow variant for that shirt. Again this can be named anything as long as it maps to “Image” on the Sana-side. That way the connector knows that it is holding an image and will transfer that to Sana correctly.

Brochure: Like with Images Sana supports having variant specific Attachments.

Configuring the connector: Entity “Category”

Mappings for categories are done the same way as for products and variants.

The first “@Context”-mapping works the same way as for Products, it tells the Connector where it can find Categories, which view it should ask for when querying Perfion and finally if any filter should be applied when selecting which Categories that should be fetched. In Figure 14 we see that Categories are found in the base feature “Section” and that the filter named “SanaCategorySearch” is applied when fetching these categories. When auto creating Sana-features a value named “SanaCategorySearch” is created for the feature “SanaSearches”, and this is the value pointed to here in the Context-node. Note that this value is only auto-created in Perfion Clients 4.5.28 or later. in earlier versions you have to create it yourself. The value auto-created has per default an empty query meaning the no categories (in the above case “Sections”) are filtered away per default. It could make sense to modify that in order to have only some Sections in Perfion becoming Categories in Sana. In most installations, though, you would create a new feature, say “WebCategories” to handle Categories in Sana, in and therefore all “WebCategories” would need to go to Sana without exceptions. But if you “share” the Section-features with, say, reporting and publishing, you may want to create a non-empty filter query. 

.id: This mapping, which is becoming the unique Id of all categories in Sana, means to take the id of the feature value. Perfion guarantees this to be unique for each value (in this case each section), so it is a good choice for a category Id in Sana as well. If you have a feature on you Sections that holds another unique, and maybe more descriptive, unique identification, feel free to map that instead of .id. Make sure, however, that it maps to “Id” in Sana and not something else and make sure that all section have a unique value for that feature.

Value: The base value of a Section in the demo database happens to hold the name of the section, so it is a good candidate for the category title in Sana. Again another feature than Value can be used.

.order: Regarding categories it makes sense to order them logically on the front end web site. In the Perfion demo database, the Section-feature does support “Custom ordering” and hereby have an order associated with them. This order can be reached using the dot-notation, in this case by using .order.

Visible: An entity in Sana can be either visible or invisible. Categories need to be made visible and this is simply done be creating a mapping where the literal value ‘1’ is shipped to a known field in Sana named “Visible”. The Sana connector recognizes literals on the quotes.

More on mappings

As previously written: Mappings are basically two different names used in two different systems meaning the same “thing”. In this case the two systems are Sana and Perfion.

When creating a mapping, the most important ones are the ones that are needed by Sana for it to work.

On the left hand side of the mapping, what we have seen so far is the following two kinds of mappings:

• Mapping a feature to a Sana Field, i.e. mapping the feature “Item Number” to the field “Id” on Products in Sana.

• Mapping a property to a field in Sana, i.e. mapping the id of a Section to the field “Id” of Categories in Sana.

There are actually two more special kind of mappings you can do: Literals and Fixed Expressions. These will be explained below:

Mapping a feature to Sana

This is what we have been doing many times in our examples. When a feature named “ShortText” is mapped to a field named “Description” in Sana it simply means that description in Sana for some product is filled with the text found in the feature “ShortText” for that product. No surprise there.

What may be a surprise, though, is that Perfion takes care of any language-mappings needed. This means, that since “ShortText” is a localized feature in Perfion, it will have (up to) 1 representation for each language. All languages set up in Settings will be mapped for all localizable features automatically to the appropriate culture Id in Sana. In the figure below this is shown the 3 languages EN, DE and DAN.

Sana has the notion of a “Default culture” in this case EN (English) maps to the Default Culture so Description for English has no “_1033” added to it. All languages not mapping to the default culture will have a “_<Culture ID>” added to them as can be seen for DE (German) and DAN (Danish).

To a large extent Perfion uses Language codes from the ISO 639-2, i.e. a three letter abbreviation for each language. Perfion has historically been using some non ISO-639-2 names in some cases (i.e. EN and DE), but generally this is not the case. Sana uses a Culture ID instead, which makes good sense since a culture is more than a language. It is also about formatting values (number formats, date formats, currency code etc.) The Sana Connector translates each language name to a culture id in Sana automatically. If you are not happy with the built-in translation it can be overwritten.

Mapping a property to Sana

For categories we already have been mapping the id- and order-properties of Sections to fields in Sana (the Id- and SortId-fields in Sana, respectively). There are more properties. In fact a property simply reads the attribute of the same name in the API-result of the feature:

Note that each section has an "id" and an "order"-attributes, which are exactly the properties we use. Besides those two there are many more properties.

Remember to use the dot-notation when mapping properties on the feature value itself, otherwise the Connector will look for a feature by the name supplied.

Sample properties:

• .id: Simply takes the id of a section. For “T-Shirts”-section the value 348 will be returned to Sana.

• Value.seq: Takes the seq-property of the Value feature name. For “T-Shirts” the value “0” will be returned to Sana.

For more information on what properties you have in the Perfion result, please get the Perfion API Documentation and look at the returned Xml. All attributes returned corresponds to properties available.

Mapping a literal (constant)

If you for some reason need a field in Sana to have a constant value, you do not need to create a feature in Perfion assigning it that value on all entities. Simply create a mapping where left most value is in apostrophes. In Figure 16 we assign the text “Title will soon be there” to all product titles.

We used that for Categories for setting the Sana Field “Visible” to “1” on all returned categories.

Mapping a fixed expression

The final kind of data that can be mapped to Sana is what is called a “Fixed Expression”. It is an expression where the connector has “hardcoded” what data in to that field on each entity (Product, category etc.).

In version 2.0.0 of the Connector only one such fixed expression exists: @GetAll(). A fixed expression can be recognized by the fact that it starts with a @-sign and ends with two parentheses.

The @GetAll() fixed expression outputs the entire entity node from the Perfion API together with the feature nodes representing features in that concrete product.

Sana cannot out-of-the-box do anything clever with the content of that field, but programmers familiar with Perfion may use it for various needs.

Note that the Features-element in the Xml has been shortened a bit for readability.

Most likely you will not need this fixed expression in your installation, but in previous versions of the Sana Connector data on this form was available, so it is kept for backwards compatibility.

Mapping an expression

Expressions, not to be confused with fixed expressions, are a well-known feature for those acquainted with the the Perfion Query Language. Expressions are available in Sana Connector 2.0.4 and newer.

Expressions allows you to “adjust” the values output from the Query Language so they better suit your needs. A Factsheet has been made describing how Expressions are used in the Perfion Query Language. Please contact Perfion Support to get this document.

Here we will give one of the most prominent examples of a usage of an expression: Formatting how multi value features should be output. Say you have a multi value feature like the feature MultiColor shown here on some product, where it has three values:

If you map this feature to Sana these values will be sent as a “Carriage return/Line –feed”-separated string. In Sana that works fine for a field on which you create a facet. But if you want to present these colors as items in an unordered list, you rather want something like:

<li>Red</li><li>Blue</li><li>Green</li>

To achieve this simply tell it to the Connector by using a so called “Expression”. In the screen shot below the two bottommost mapping maps the content of the MultiColor-feature to two different fields in Sana: MultiColorAsFacet and MultiColorAsHtml. For the first, having no expression, its multiple values are simply passed as a Carriage Return/Linefeed-delimited string. For the second, MultiColorAsHtml, having an expression, this is formatted into list items as shown above.

The @FormatMultiValues expression works like this:

@FormatMultiValues(<BeforeValue>{Value}<AfterValue>|<BetweenValue>)

{Value} simply outputs the feature value. Instead of <BeforeValue> you write the string you want to appear before each value. Similarly with <AfterValue>. Finally after the | (pipe) you write the <BetweenValue>, which is string you want to appear between a pair of values. In the case of list items, the <BeforeValue> is “<li>”, the <AfterValue> is </li> and finally the <BetweenValue> should be blank (simply by having nothing after the pipe). It is important to have the pipe also in this case, since default <BetweenValue> is a semicolon.

You may create as many mappings as you want using expressions, and the expressions may be used on the same feature or on different features. Note, though, that you need a unique field name (“Sana To”) for each mapping you create.

In Sana the result of the above two are shown here (in the xml-encoded data sent to Sana):

Two kinds of fields in Sana

When doing mappings, in the “Sana To”-feature of the mapping we write the name of the field we want to fill data into in Sana. Sana (and hereby also the Connector) distinguishes between two kinds of fields:

• Known fields: Examples of such could be Id, ProductId, Title and Description. These are fields that Sana is aware of and knows what to do with. For a product Sana knows that in Id it will find the unique if of a product and in Title it will find the title of it etc.

• Custom fields or Extra fields: These are fields that Sana does not know anything about, but can actually still do something clever about.

Known Sana Fields

It is different for each entity what is reckoned as a known field and what is a custom field. The table below shows the fields the Connector considers known fields to Sana:

Figure 19: The field names recognized by the Connector. Field names not listed here are treated as Custom Fields.

This is opposed to names that are not recognized as described in the following section.

Custom Sana Fields

Anything not being a known Sana Field is automatically considered a custom field or extra field. Back in previous section we had a field named “Manufacturer” mapped from a feature in Perfion named the same. Since it is not a known field, it must be a custom field.

What happens is that the connector recognizes the fact that it is a custom field and copies it to Sana accordingly. What you will have is a field named “[Perfion] Manufacturer” available in Sana, and this can be used for searching, filtering and facets. Later section will guide you through creating a feature in Perfion through having it show up for use in Sana.

Languages

As described the Perfion Connector auto translates from Perfion Language Names to Sana Culture Id’s. When you are not happy with the culture id picked for some Perfion language you can use the mappings for the entity named “Language Deviation”. There are basically two reasons for not being happy with the picked language:

• Say you picked the EN language in Perfion to hold English texts, this will map to Culture Id 1033 (US English). If you are running a, say “British English” site, you would maybe rather have British English instead (Culture Id 2057).

• Say you have one language in Perfion, German, but want your site both to be used by Germans and Austrians, so you need the same German texts mapped not to only one but to two different cultures.

Both the above can be achieved using the mappings on Language Deviations:

The 1^st mapping maps EN to 2027 (British English) instead of US English.

The 2^nd and 3^rd mapping maps the same language (DE) to both German (1031) and Austrian (3079) cultures in Sana.

There is no limit to how many cultures a single Perfion language can be mapped to.