This Output Kind was introduced in Perfion 4.5 2019 R1, and should not be confused with outputting an attribute as a Field as described in Section Field where an attribute from a Perfion Query Result is output as a Field.
The Output Kind Attribute is used to “decorate” an already existing Output-element with an attribute.
Attribute | ||||
What can be output | Supports | Supported Entities | ||
a Features a Attributes a Literals | r Multi value features (First from Perfion 2024 R1 SR2) a Localizable features r Output Kind Parameters | a Site a Category a Product a Variant | ||
Sample Mappings | ||||
| ||||
Sample output | ||||
| ||||
Table 1: Summary of Output Kind Attribute.
Notice the mapping with Output Kind Attribute. In the example in Table 1 the value of the feature CupSize is mapped to an element named NoOfCups@size an attribute named size. The “@” makes sure that the data get’s mapped on an attribute on the output field and not as a separate output field.
It even works for fields originating from a *-mapping. In addition, fields having their data coming from a Literal or Attribute can be decorated.
It is not only Fields that can be output using the Attribute Output Kind. Also Image-, Attachment-, Url-, RelatedProduct- and RelatedCategory-elements can be decorated.
| Info |
|---|
NOTE: Do not use attribute names id, parentId, name, perfionname, culture, modifieddate, ecommerceproduct and ecommercevariant, since the ECommerce API already uses them. |
Combining non-localizable with localizable features on fields and attributes
It is worth looking into localizable features and combining localizable features with non-localizable features. In Table 1 we combined NoOfCups and CupSize-features that happened both to be non-localizable. Similarly combining two features that are both localizable works as expected. However, what about making a localizable feature and map it to a Field while a non-localizable is output as an Attribute on that same Field. How would that work? Let us consider the remaining 3 localization-combinations in the following example:
Example
Consider the following data on a product:
ItemName- and Color-features are localizable. While RRP (RetailPrice) and RetailPriceCurrency are not. For the sake of simplicity, assume that we have two languages in play: English and German.
Let us see how the possible combinations are handled by the ECommerce API:
Combining two localizable features | |||
Mappings |
 
| ||
Description | Both ItemName and Color are localizable features, so for each language the ItemName is output as a separate Field named Title for each culture. This makes it obvious that each localizable Color-value-attribute should be put on the Field matching the culture. I.e. the English Color is matched with the English Title and output here.
| ||
Result |
| ||
Combining a localizable Field with a non-localizable attribute | |||
Mappings |
 
| ||
Description | Here the localizable ItemName still outputs a Field named Title for each language/culture. The non-localizable RetailPriceCurrency is simply added to each one.
| ||
Result |
| ||
Combining a non-localizable Field with a localizable attribute | |||
Mappings |
 
| ||
Description | Here the non-localizable feature RetailPrice is given the localizable feature Color as attribute. Since RetailPrice is only output once, color is output only once. The ECommerce API picks the value of the primary language which is the first language specified in Settings (See Languages-setting).
| ||
Result |
| ||
Table 1: 3 of the 4 different combinations of localizability of 2 features.
The last combination should be avoided, since it does not output localizable data other than that in default language (in Table 1 it is the colors in any language but English that are lost). Unfortunately, this hits the often-wanted combination of outputting some sort of measure combined with its unit. Consider this example:
| Code Block |
|---|
<Field name="TopSpeed" unit="km/h">206</Field> |
Here TopSpeed is assumed to be non-localizable and TopSpeedUnit to be localizable (since it would be “Kilometers per hour” or “km/h” in English and “Kilometers pro Stunde” or “km/s” in German). However, as we saw from Table 1, this combination gives us problems. There are multiple solutions to this:
Solution #1: Output both as Fields
| Code Block |
|---|
<Field name="TopSpeed">206</Field> <Field name="TopSpeedUnit" culture="en-US">km/h</Field> <Field name="TopSpeedUnit" culture="de-DE">km/s</Field> |
Here the foreign system must somehow know how to connect the two.
Solution #2: Make TopSpeed localizable and give it same value in all languages
| Code Block |
|---|
<Field name="TopSpeed" unit="km/h" culture="en-US">206</Field> <Field name="TopSpeed" unit="km/s" culture="de-DE">206</Field> |
This gives the result wanted, but forces users to maintain the same value for all languages.
Solution #3: Same as Solution #2 but using a self-remote to output same value in all languages
This outputs the same as Solution 2. The idea is to make a self-remote, that is a query “localizing” all features you need to pair up with their appropriate units. It is beyond the scope of this document to describe how to do a self-remote in Perfion. Consult Perfion to get help if you are in doubt.
Outputting Multi Value-attributes (Requires Perfion 2024 R1 SR2)
From Perfion 2024 R1 SR2 it is now possible to use multi value features to create attributes on multi value outputs. This can for example be used to give a multi value image feature a caption or maybe an “alternative text” or maybe a multi value attachment a nice display name to be used on a link. It works both for localizable and non-localizable features and it even works when combining multi value image-/attachment-features.
In the following we will take a look at some examples.
Adding description-attributes to a multi value image-feature | |||
Mappings |  | ||
Description | Here WebImages is a multi value, explicit image feature and WebImageDescription is a multi value, explicit string feature. Both features have “Sortable” checked in Perfion, since the images are paired with strings using their position. The image below shows a single product holding 3 WebImages with 3 WebImageDescriptions. Notice how each image matches its description by their position in the lists.  | ||
Result |
Notice, by looking at the “OriginalFileName” how each description is added to the correct Image-output in a description-attribute. | ||
Notice how each description is added to the Image-output in a description-attribute.
The same can be done for localizable images. Here it is allowed to have a different number of image in each language. The important thing is that the number of images in some language must match the number of descriptions in that language.
Adding description-attributes to a localizable, multi value image-feature | |||
Mappings |
| ||
Description | Here LocalizableWebImages is a multi value, localizable, explicit image feature and LocalizableWebImageDescription is a multi value, localizable, explicit string feature. Both features have “Sortable” checked in Perfion, since the images are paired with strings using their position, it is important that both can be manualle sorted. The image below shows a single product holding 3 LocalizableWebImages with 3 LocalizableWebImageDescriptions. Notice how each image in each language matches its description by their language and position in the lists.
Notice that the English value only holds 2 images while the German holds 3. This is fine, as long as the number of descriptions matches in each language. | ||
Result |
Notice, by looking at the “OriginalFileName” how each description is added to the correct Image-output in a description-attribute. | ||
| Table of Contents |
|---|
The final example shows how multiple image features may be combined and still have their description attribute set. This requires a string-feature for each Image-feature. For simplicity the example combines two non-localizable Image-features, but they might as well have been localizable.
This Output Kind was introduced in Perfion 4.5 2019 R1, and should not be confused with outputting an attribute as a Field as described in Section Field where an attribute from a Perfion Query Result is output as a Field.
The Output Kind Attribute is used to “decorate” an already existing Output-element with an attribute.
Attribute | ||||
What can be output | Supports | Supported Entities | ||
a Features a Attributes a Literals | r Multi value features (First from Perfion 2024 R1 SR2) a Localizable features r Output Kind Parameters | a Site a Category a Product a Variant | ||
Sample Mappings | ||||
| ||||
Sample output | ||||
| ||||
Table 1: Summary of Output Kind Attribute.
Notice the mapping with Output Kind Attribute. In the example in Table 1 the value of the feature CupSize is mapped to an element named NoOfCups@size an attribute named size. The “@” makes sure that the data get’s mapped on an attribute on the output field and not as a separate output field.
It even works for fields originating from a *-mapping. In addition, fields having their data coming from a Literal or Attribute can be decorated.
It is not only Fields that can be output using the Attribute Output Kind. Also Image-, Attachment-, Url-, RelatedProduct- and RelatedCategory-elements can be decorated.
| Info |
|---|
NOTE: Do not use attribute names id, parentId, name, perfionname, culture, modifieddate, ecommerceproduct and ecommercevariant, since the ECommerce API already uses them. |
Combining non-localizable with localizable features on fields and attributes
It is worth looking into localizable features and combining localizable features with non-localizable features. In Table 1 we combined NoOfCups and CupSize-features that happened both to be non-localizable. Similarly combining two features that are both localizable works as expected. However, what about making a localizable feature and map it to a Field while a non-localizable is output as an Attribute on that same Field. How would that work? Let us consider the remaining 3 localization-combinations in the following example:
Example
Consider the following data on a product:
ItemName- and Color-features are localizable. While RRP (RetailPrice) and RetailPriceCurrency are not. For the sake of simplicity, assume that we have two languages in play: English and German.
Let us see how the possible combinations are handled by the ECommerce API:
Combining two localizable features | |||
Mappings |
| ||
Description | Both ItemName and Color are localizable features, so for each language the ItemName is output as a separate Field named Title for each culture. This makes it obvious that each localizable Color-value-attribute should be put on the Field matching the culture. I.e. the English Color is matched with the English Title and output here.
| ||
Result |
| ||
Combining a localizable Field with a non-localizable attribute | |||
Mappings |
| ||
Description | Here the localizable ItemName still outputs a Field named Title for each language/culture. The non-localizable RetailPriceCurrency is simply added to each one.
| ||
Result |
| ||
Combining a non-localizable Field with a localizable attribute | |||
Mappings |
| ||
Description | Here the non-localizable feature RetailPrice is given the localizable feature Color as attribute. Since RetailPrice is only output once, color is output only once. The ECommerce API picks the value of the primary language which is the first language specified in Settings (See Languages-setting).
| ||
Result |
| ||
Table 1: 3 of the 4 different combinations of localizability of 2 features.
The last combination should be avoided, since it does not output localizable data other than that in default language (in Table 1 it is the colors in any language but English that are lost). Unfortunately, this hits the often-wanted combination of outputting some sort of measure combined with its unit. Consider this example:
| Code Block |
|---|
<Field name="TopSpeed" unit="km/h">206</Field> |
Here TopSpeed is assumed to be non-localizable and TopSpeedUnit to be localizable (since it would be “Kilometers per hour” or “km/h” in English and “Kilometers pro Stunde” or “km/s” in German). However, as we saw from Table 1, this combination gives us problems. There are multiple solutions to this:
Solution #1: Output both as Fields
| Code Block |
|---|
<Field name="TopSpeed">206</Field> <Field name="TopSpeedUnit" culture="en-US">km/h</Field> <Field name="TopSpeedUnit" culture="de-DE">km/s</Field> |
Here the foreign system must somehow know how to connect the two.
Solution #2: Make TopSpeed localizable and give it same value in all languages
| Code Block |
|---|
<Field name="TopSpeed" unit="km/h" culture="en-US">206</Field> <Field name="TopSpeed" unit="km/s" culture="de-DE">206</Field> |
This gives the result wanted, but forces users to maintain the same value for all languages.
Solution #3: Same as Solution #2 but using a self-remote to output same value in all languages
This outputs the same as Solution 2. The idea is to make a self-remote, that is a query “localizing” all features you need to pair up with their appropriate units. It is beyond the scope of this document to describe how to do a self-remote in Perfion. Consult Perfion to get help if you are in doubt.
Outputting Multi Value-attributes (Requires Perfion 2024 R1 SR2)
From Perfion 2024 R1 SR2 it is now possible to use multi value features to create output attributes on multi value outputs-feature output. This can for example be used to give a multi value image feature a caption on each image or maybe an “alternative text” or maybe a . It can also be used to give multi value attachment attachments a nice display name title to be used on a link. It Outputting multi value features works both for localizable and non-localizable features and it even works when combining two or more multi value image-/attachment-features.
In the following we will take a look at some examples.
Adding description-attributes to a multi value image-feature
Mappings
Description
In the the first example WebImages is a multi value, explicit image feature and
WebImageDescriptionWebImageDescriptions is a multi value, explicit string feature.
BothImportantly, both features have “Sortable” checked in Perfion, since the images are paired with the strings using their position. The image below shows a single product holding 3 WebImages with 3 WebImageDescriptions. Notice how each image matches its description by their position in the lists.
Adding description-attributes to a multi value image-feature | |||
Mappings | | ||
Description | Sample output product “Example 1” to output in the result below: | ||
Result |
Notice, by comparing the value in description-attribute with the “OriginalFileName” how each description is added to the correct Image output in a description-attribute. | ||
Notice how each description is added to the Image-output in a description-attribute.
The next example shows that the same can be done for localizable images. Here Features LocalizableWebImages and LocalizableWebImageDescriptions are, as their names imply, multivalue, localizable features being an Image and a String-feature, respectively. Note how it is allowed to have a different number of image in images for each language. The important thing is that the number of images in some language must match matches the number of descriptions in that language.
Adding localizable description-attributes to |
a localizable multi value image- |
feature | |
Mappings | |
Notice the small trick used to let the ECommerce API know which “description-feature” goes with which “image-feature”. The trick is simply to add the feature name in parenthesis after the Field-name (here Images).
Description
 | |||
Description | Sample output product “Example 2” to output in the result below:  | ||
Result |
Notice, by comparing the value in description-attribute with the “OriginalFileName” how each description is added to the correct Image output in a description-attribute. |
The final example of adding multi value attributes to multi value images shows how two multi value image-features can be combined to one output (below named “Images”) can still have a description added. In the below example WebImages and MoreWebImages are both multi value, explicit image features and both WebImageDescriptions MoreWebImageDescriptions are multi value, explicit string features. All 4 features have “Sortable” checked in Perfion, since the images are paired with strings using their position, it is important that both can be manually sorted. The image below shows a single product holding 2 WebImages and 3 MoreWebImages with their corresponding “WebImageDescription-features” holding the exact same number of strings.
It is important to notice the small trick that tells the ECommerce API that descriptions for WebImages can be found in WebImageDescriptions and that those for MoreWebImages can be found in MoreWebImageDescriptions. The trick is simply to mention the originating feature in parenthesis after the “Output To”-name. So for WebImageDescriptions we output to Images(WebImages)@description instead of just Images@description. Same is done for MoreWebImages and MoreWebImageDescriptions.
Adding description-attributes to when combining multiple multi value image-features | ||||
Mappings | Notice the small trick used to let the ECommerce API know which “description-feature” goes with which “image-feature”. The trick is simply to add the feature name in parenthesis after the To-name (here Images). | |||
Description |
| |||
Result |
Notice, by looking at the “OriginalFileName” how each description is added to the correct Image output in a description-attribute. | |||
Final note on multi value attributes
The above examples show adding attributes to Images. The exaxt same thing can be done for Attachments and Urls and to some extend also Fields. Fields cannot be combined (ie. multiple features being mapped to same Field) so attributes cannot be combined either.
All examples emphasize that you need the same number of values in the “Attribute feature” as in the Feature you want to decorate. That obviously makes sense. Should you have an extra value (an extra description) it will not be used, and should you miss a value (miss a description) the last value in the output will not de decorated (i.e. the last image will not get a description).
| Table of Contents |
|---|