> For the complete documentation index, see [llms.txt](https://docs.fact-finder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fact-finder.com/webcomponents-overview/web-components-4.x./guides/essentials/field-roles.md).

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

{% hint style="warning" %}
During the setup of a channel in the FactFinder-UI, you have to assign each of the `fieldRoles` listed above to one field/column in your product database.
{% endhint %}

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](file:///documentation/4.x/currency-guide) on your product detail page, you have to map `price` to `prix` in the `factfinder.communication.fieldRoles` property in your front-end.

{% hint style="info" %}
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.
{% endhint %}

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

<details>

<summary>Example product database</summary>

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

</details>

This is how you set the `fieldRoles`:

{% hint style="warning" %}
Both event listeners have to be declared before the Web Components scripts are loaded, or you could miss the event, **and your code is never executed**!
{% endhint %}

```html
<script>
    document.addEventListener("ffReady", function (event) {
        const factfinder = event.factfinder;
        factfinder.communication.fieldRoles = {
            campaignProductNumber: "campaignId",
            imageUrl: "image",
            masterArticleNumber: "masterId",
            price: "RRP",
            productName: "name"
        };
    });
</script>
<script defer src="pathToFFWebComponents/dist/bundle.js"></script>
```

{% hint style="info" %}
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.
{% endhint %}

### 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](https://github.com/FACT-Finder-Web-Components/demos/blob/release/4.x/ff-record-list/index.html) 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

{% stepper %}
{% step %}

### 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.
{% endstep %}

{% step %}

### Define the `fieldRoles` when the `ffReady` event is fired

{% endstep %}

{% step %}

### Define the `fieldRoles` before you do a request

This *should* always be the case if you followed the previous step.
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fact-finder.com/webcomponents-overview/web-components-4.x./guides/essentials/field-roles.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.