Field Roles
Map product fields to FactFinder roles before non-search API requests.
This section describes an essential part of the integration of FactFinder using FactFinder Web Components. FactFinder and FactFinder Web Components depend on a proper definition of these roles. A missing definition can result in unexpected behaviors that might look like bugs.
Certain fields/columns in FactFinder's product database can have special meanings. For example, a price field. Many of FactFinder's features, such as Tracking, require knowledge of these special meanings. Since every customer might use custom field names, there needs to be a mapping between the meaning of a field and its field name.
We call these meanings fieldRoles. During the set-up process of a new channel in the FactFinder-UI, you assign a field to each one of the fieldRoles.
These are the fieldRoles:
brand– name of manufacturer.campaignProductNumber– product number that is used to reference the product in the campaign manager.deeplink– URL of the product page.description– product description.displayProductNumber– the displayed product number.ean– EAN.imageUrl– product image URL.price– price field.productName– product name.trackingProductNumber– product number used in tracking.masterArticleNumber– product number of the main product if product variants are used.
This means that for FactFinder and FactFinder Web Components to process your data properly, you also need to provide a mapping of fieldRoles to field names in your front-end before you request data via FactFinder Web Components from any API except the search API.
More specifically, to use the following elements, it is mandatory to define the fieldRoles property on the client side:
<ff-recommendation><ff-similar-products><ff-communication currency-code ...><ff-suggest><ff-checkout-tracking><ff-tag-cloud><ff-campaign-pushed-products>(Tracking) loaded via<ff-campaign-landing-page>,<ff-campaign-products>, or<ff-campaign-shopping-cart>
In other words: You might have a field called prix that contains the product's price in your product database. During set-up, you assign the role price to your field prix in the FactFinder-UI. In order to use the Currency Attributes on your product detail page, you have to map price to prix in the factfinder.communication.fieldRoles property in your front-end.
How to define fieldRoles on the FactFinder Web Components side
You need to do this when the ffReady event is dispatched so ff-communication knows the correct mapping before your API requests are sent. fieldRoles is a property of factfinder.communication.
Here is an example of how your product database might look after the set-up.
This is how you set the fieldRoles:
How to look up your fieldRoles
As mentioned above, the search API can be queried without providing the fieldRoles property. This is because a response from the search API contains the fieldRoles property as it is defined in FactFinder.
You can simply query the search API and look at the response JSON to find the fieldRoles property. Then you can use that object in your front-end assignment for the factfinder.communication.fieldRoles property.
Example:
You can check out the record-list demo and adjust the ff-communication parameters to match your set-up and use the search box in the demo to submit any search query. In your dev-tools' network tab, you can look at the JSON response under searchResult.fieldRoles to find the fieldRoles you will need.
Integration Checklist
Last updated
Was this helpful?