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 previous chapter we already used this mapping.
Field - Output Kind Field | ||||
What can be output | Supports | Supported Entities | ||
a Features r Attributes r Literals | r Multi value features r Localizable features r Merging of features | a ProductCategory a Product a Variant | ||
Sample Data | ||||
  | ||||
Sample Mappings | ||||
 
| ||||
Sample output | ||||
| ||||
Table 1: 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 | ||
a Features a Attributes a Literals | a Multi value features a Localizable features r Merging of features | a ProductCategory a Product a Variant | ||
Sample Data | ||||
| ||||
Sample Mappings | ||||
  | ||||
Sample output | ||||
| ||||
Table 2: 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 2).
The following sub sections walks through all the mappings showed in Table 2.
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.
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.
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.
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.
Outputting constants has no notion of localizability and multi values.
Multi values
A multi value in Perfion is simply a feature that can hold multiple values at the same time. In Table 2 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).
| Info |
|---|
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. |
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). 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
This means that the following “chunk of data” will be output for that field.
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:
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 3:
Field - Output Kind Field – Wild card mapping | ||||
What can be output | Supports | Supported Entities | ||
a Features r Attributes r Literals | a Multi value features a Localizable features r Merging of features | a ProductCategory a Product a Variant | ||
Sample Data | ||||
  | ||||
Sample Mappings | ||||
 | ||||
Sample output | ||||
| ||||
Table 3: Summary of fields being output using the wild card mapping
The fields output in Table 3 can be directly compared with the fields output in Table 2. In Table 3, 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 3 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, seeTable 2) 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 previous chapter, 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 | ||
a Features r Attributes r Literals | a Multi value features a Localizable features (only partly) a Merging of features | r ProductCategory a Product a Variant | ||
Sample Data | ||||
| ||||
Sample Mappings | ||||
  | ||||
Sample output (from the GetProductImages request) – Connector Version 3.0.1 and below | ||||
| ||||
Sample output (from the GetProductImages request) – Connector Version 3.0.2 and above | ||||
| ||||
Table 4: Using Output Kind Image to output images.
| Info |
|---|
NOTE: The two different results depending on connector version. |
| Info |
|---|
NOTE: Sana request used here is GetProductImages, not GetProducts, which does not return images. |
In the example in Table 4, 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 4, 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.
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.
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. 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 5 shows you how it works:
Attachment | ||||
What can be output | Supports | Supported Entities | ||
a Features r Attributes r Literals | a Multi value features a Localizable features (only partly) a Merging of features | r ProductCategory a Product a Variant | ||
Sample Data | ||||
 | ||||
Sample Mapping | ||||
 
| ||||
Sample output | ||||
| ||||
Table 5: 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 5, we have here our product having both some manuals in the feature Instructions 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 http://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.
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 5 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 5 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 idbb71a5ae-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 5 shows it. Here 1923-16.pdfis 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 Making a better description (title on attachment-links in Sana).
Note this requires Connector Version 3.2.2 and above combined with Perfion API v. 2024 R1 SR2.
As can be seen from the above example, Sana allows for a Description-element in attachments. The connector fills this Description-element with a value as follows:
For Attachment-mappings the FileName is simply output (without extension)
For Url-mappings the Url is output having any http:// or https://-prefix removed.
Perfion version 2024 R1 SR2 allows you to create multi value and localizable attributes allowing you to supply a custom title coming from another feature value. Consider the following example:
Attachment - Customizing description | ||
Sample Data | ||
The same data as before, except that a feature for Descriptions has been added for both the “InstructionsPDF”- and “ManufacturerWeblink”-features.  It is important to create these “description-features” so that they match the feature they should make descriptions for on “Localizability” and whether they should be multi value or not. If making a feature multi value make sure that “Allow ordering” is checked on both the feature holding the decorated feature (here Instructions) and the decorating value (here InstructionsPDFDescriptions). This is needed to order their feature values so first pdf-doc is matched with first description, second pdf-doc matches second description and so on. | ||
Sample Mapping | ||
Notice the two new Attribute-mappings mapping from the two description-features to their corresponding Attachment/Url-feature:  It is important that the attribute is named exactly “description”. Otherwise it will not be picked up by the connector, which will then return to auto-filling it like described anove. | ||
Sample output | ||
The output reflects the changes. Now the descriptions are coming from the two-description features as shown here:
The ECommerce API manual describes the Attribute-feature further. Notice that this only works from Perfion API version 2024 R1 SR 2 combined with Connector 3.2.2. |
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.
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.
| Info |
|---|
NOTE: 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 | ||
a Features r Attributes r Literals | a Multi value features r Localizable features a Merging of features | r ProductCategory a Product r Variant | ||
Sample Data | ||||
 | ||||
Sample Mapping | ||||
 
| ||||
Sample output | ||||
| ||||
Table 6: Using Output Kind RelatedProduct for outputting related products.
As can be seem from Table 6 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 6 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 notedyou 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, 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 | ||
a Features r Attributes r Literals | a Multi value features r Localizable features r Merging of features | r ProductCategory a Product r Variant | ||
Sample Data | ||||
| ||||
Sample Mapping | ||||
 
| ||||
Sample output | ||||
| ||||
Table 7: Using Output Kind RelatedCategory for outputting categories
As the result in Table 7 shows, categories are output with their ids. As you remember from 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 7 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.
| Table of Contents |
|---|