For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

The fieldRoles are configured in the FactFinder-UI during the setup process. It is essential that the roles you define in the browser match the ones defined in FactFinder.

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.

Example product database
id
campaignId
masterId
RRP
image
name

1

21

14.45

http://...

Nerf Gun

2

22

19.99

http://...

Ergonomic Keyboard

3

23

12.5

http://...

Rubber Duck

This is how you set the fieldRoles:

We omitted some roles in this example, but you always have to set all fieldRoles in the back-end as well as in the front-end.

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

1

All fieldRoles are defined properly

The value in your definition has to match the field's name in your product database. This is case sensitive.

2

Define the fieldRoles when the ffReady event is fired

3

Define the fieldRoles before you do a request

This should always be the case if you followed the previous step.

Last updated

Was this helpful?