Attribute

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
Open
Sample output
<Response>    <Result>    <TotalCount>1</TotalCount>    <Product>       <!-- Fields from ERP and Perfion omitted here for brevity -->       <field name="NoOfCups" value="4" size="Medium" />        <field name="Volume" value="0.35" unit="L" />    </Product>    </Result> </Response>

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.

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:

Open

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:

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:

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 

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 

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.

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.

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.

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.

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:

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:

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 

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 

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 possible to use multi value features to output attributes on multi value-feature output. This can for example be used to give a multi value image a caption on each image or maybe an “alternative text”. It can also be used to give multi value attachments a nice display title to be used on a link. 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. In the the first example WebImages is a multi value, explicit image feature and WebImageDescriptions is a multi value, explicit string feature. Importantly, 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.

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. 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 images for each language. The important thing is that the number of images in some language matches the number of descriptions in that language.

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.

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