Sana Connector 2.0 - Various tasks
- Morten Lindequist Køhler
Creating a custom field in Sana
This guide will take you through the entire process of creating a feature in Perfion, filling data in it and finally creating it as a custom field in Sana.
For the example we will create a feature named “CountryOfOrigin” which will hold the country the product was manufactured in.
First we do the following:
Open Perfion
Go to “Features”
Finds the “String” node, right-click it and select “Add new…”
This will bring up the Create Feature Dialog:
Note that, if you support multiple languages you would need to create a caption for each language you want represented on your web site. The Connector will automatically pass the localized captions to Sana. Along the same lines you may want to consider making it localizable, so that the values itself are localized. The Connector will automatically sent all localized values to correct culture in Sana.
Now it needs to go onto the configuration for the base feature we use for products. In this setup this Feature is called Product:
Find the Product-feature (or more precise the base feature that holds the products that you want to send to Sana).
Right-click and select “Configuration”.
This brings up the configuration on products on the right hand side. Drag in “CountryOfOrigin” and place it somewhere in the configuration:
Click “Web” and click the “WebDetail”-checkbox next to CountryOfOrigin. This is not necessary, but means that “CountryOfOrigin” will show up in that view (that is WebDetail).
Now go to Web (the scene containing your products on the right hand side), pick the WebDetail-view:
Update all the products you want (likely all) with their country of origin. It doesn’t matter on which level in the inheritance hierarchy you put it, as long as each product gets a correct “Country of Origin”.
When done we only need to map it to Sana:
Go to “Feature Data”
Find the string “Node”, and the child “Sana Entity”.
Open the “Product”-row on the right hand side.
Right click in the grid and click “Add new”.
Now type in “CountryOfOrigin” as the feature name.
Also type in “CountryOfOrigin” as the name for the (custom) Sana Field.
That is it! You have done what you need to do in Perfion.
Now let us turn to the Sana Admin-interface.
First click the “Tools”-button and pick scheduled tasks.
Since we have made changes to Sana Mappings (introducing a new field) we first need to run “Get information import”. Click “Start” here. After that has run, Sana is aware of the field.
Let us add the new field to both the products lists and product detail pages:
Go to “Setup” and “Products”
Click the “Product specifications”-tab.
Here you can now add the “[Perfion] Country Of Origin”-field picking it in the bottommost drop down.
When done, notice that Sana per default assumes that it should be shown both on the Details- and List-page.
Click “Save changes” to save the new field on Products.
Now we can add it as a keyword and a filter field:
Expand the “Setup”-menu to the left and click “Erp integration”.
This brings up the following window:
Add “[Perfion] Country Of Origin” both as a Keyword field and as a Filter field.
Click save when done.
As Sana suggests in the blue top bar, you will now need to re-index all your products, since Sana never seen the “Country Of Origin”-feature before. Before we do that let us add it as a facet to Sana:
Go to Setup, and select “Navigation & search”
Click the “Facetted filters”-tab
Add “[Perfion] Country Of Origin” as a facet.
Your screen should now look like this:
Finally for all this to work. Go to “Tools” pick “Scheduled tasks” and pick “Rebuild index” for the product task. If you have many products this may take a while.
When done go to the front end and enjoy the result. Now
You may search for country and finding products (i.e. type “Denmark” in Search-box and Sana will quickly returns all products associated with that search term.
Notice the facets to the left of any list screen
Go to a product detail page, click “Specifications”-tab, and the “Country of Origin” should be one of the specifications listed:
Variants in multiple dimensions
Both Sana, Perfion and the Perfion Connector supports variants in multiple dimensions. Even if your ERP-system doesn’t support multiple dimensions, the Connector can still present variants in multiple dimensions for Sana. The ERP-system must support variants, however, to be able to have variants in Sana.
Prerequisites:
You need variants in your ERP-system
You must have enabled variants in Settings
You must have a feature containing value “Product” for products and “Variant” for “Variants”.
You must have made the needed mapping on the Variant entity and configured and filled out the necessary features on all Products/Variants´(Features “SanaVariant”, “SanaProduct” and “SanaVariantTitle”).
This means that you have variants in Sana, and should be able to produce results like:
While this allows the customer to buy variants, it does make the variant selection cumbersome. It may work out with 8 variants as here (2 colors, both in 4 sizes) but imagine 12 colors in 8 sizes!
What you need is multiple dimensions, in this case 2: Color and Size. Let us take a look at the data in Perfion:
As seen on the figure above, the 8 variants are organized nicely in dimensions, first the 4 size variants that are black, followed by the 4 size variants that are red. And note the Color- and size-features. They are holding exactly the information needed to handle dimensions: All black variants have color “Black” etc. Same goes for size where each Variant is marked with their correct size.
To tell the Sana Connector that some product have their variants organized in dimensions like the above, add a feature named “SanaVariantDimensions” to the configuration of Products. Add that feature to the configuration of products. When done it should appear empty in the list. Now for each product that has their variants organized in dimensions, write the feature names doing that as a value of that feature.
Now the connector ships dimension-information to Sana resulting in the following presentation of the otherwise exactly same product:
NOTE: The order in which the dimensions appear in (here first “Color”, then “Size”) is controlled by the order they appear in in the “SanaVariantDimensions”-feature.
The order of the actual values appear in (eg. “XL” is shown first, then “L”, then “M” etc. for “Size”), is controlled by which Sort Order they appear in in Perfion (Make sure to pick “Custom Sort Order” when creating the features used to represent variant dimension values):
To reorder them, pick the size you want to move and use Alt + “Up arrow” or Alt + “Down arrow”.
Customizing the Connector
The Sana Connector utilizes Perfion Queries and xsl-queries to process requests from Sana. The connector holds these files in 5 different folders in “<SiteFolder> => Perfion => Configuration”:
Simple: Simple corresponds to “Simple”-mode. This is the recommended mode to run the connector in.
All files in this folder are auto-generated by the connector when it starts.
Advanced: Switching to “Advanced”-mode makes the connector look in the Advanced folder for its file. When the connector is installed, this folder contains the exact same files as are auto generated to the “Simple”-folder. But as opposed to files in “Simple”-folder, files in the “Advanced”-folder can be customized since they are now being written by the connector.
Installing a new connector will update the content of this folder.
Custom: Usually, if you want to customize something, you only want to customize a few files. Copying a file to this folder will override the similarly named file from the “Simple”- or “Advanced”-folder (depending on mode).
This folder will be left untouched by an upgrade.
Utility: This folder contains a lot of files with utility-xsl-templates. Generally this should be left untouched. If you need to modify something in here, consider doing the change in documents found in Simple/-Advanced folder instead.
This folder will have its content renewed on an upgrade.
Settings: The configuration from Perfion is written to xml-files in this folder. Simply to be able to access the configuration from the xsl-templates.
Files in this folder are continuously being written to by the connector, most notably, when a GetSettings-method is called.
Beneath the “Simple”- or “Advanced”-folder, depending on which mode you have chosen, you will find a “Debug”-folder. This folder contains the results and intermediate results from the different methods in the connector. The files in this folder are name such that if you sort this folder by name the order the files appear in corresponds to the order in which they are run.
Generally when some method is run by the connector the following steps are run (here shown for the method “GetProducts”):
30_GetProducts_00_SanaRequest.xml
This contains is the original request from Sana.30_GetProducts_01_ErpResult.xml
This contains the answer from the Erp-system for this request.30_GetProducts_02_PerfionQuery.xml
This contains the Query-template for the Query about to be run by Perfion.30_GetProducts_03_PerfionQueryParametersApplied.xml
This contains the resolved query about to be run by Perfion.30_GetProducts_04_PerfionQueryResult.xml
This is the result of the Perfion Query as obtained through calling the Perfion API.30_GetProducts_05_XslTransformation.xml
This file contains the Xsl-transformation that will transfer the Perfion Query Result into something resembling Sana’s input format to a larger extend.30_GetProducts_06_TransformedResult.xml
This is the transformed result
In case of the GetProducts two more “round trips” retrieving and formatting data from Perfion are needed to fetch RelatedProducts and Variants, respectively. The files used to do that are matching the following file-patterns “40_GetRelatedProducts*.*” and “50_GetVariants_*.*”.
60_MergeProductsWithErpProducts_05_XslTransformation.xml
In order to merge data for the products found in both the Erp-system and Perfion this xsl-transformation is run.60_MergeProductsWithErpProducts_06_TransformedResult.xml
This file contains the final result returned to Sana.
The content of any of those files can be customized simply by copying the file to the “Custom”-folder and doing the modifications necessary here.