> 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/oxid/sdk-v6.x-sdk-v5.x/sdk-v5.x/backend-configuration.md).

# Backend configuration

Configure the OXID module, proxy, features, and feed export.

## Backend configuration

After activation, open **Extensions → Modules → FACT-Finder® Web Components | Omikron Data Quality GmbH → Settings**.

### Main settings

![Main settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/main-settings.png)

Enter the credentials and connection details supplied for your FactFinder instance.

* **Server URL** — Include the protocol and version-specific endpoint. Use `FACT-Finder-7.3` for version 7.3 or `fact-finder` for NG.
* **Channel** — Set the correct channel for each active shop language.
* **Import and fetch credentials** — Supply the usernames and passwords used by each operation.
* **Authorization prefix and postfix** — FactFinder NG does not need these values.
* **Version** — The module supports FactFinder 6.9 through NG.
* **API version** — Select `v4` or `v5`.

Incorrect version settings can prevent Web Components from connecting to FactFinder.

### Buttons

![Buttons](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/configuration-buttons2.png)

* **Test Connection** verifies credentials. You do not need to save first. It uses the `de` channel input.
* **Export Feed** triggers a manual export. See [Export methods](https://docs.fact-finder.com/oxid/sdk-v6.x-sdk-v5.x/sdk-v5.x/export-methods.md).
* **Test FTP Connection** checks the configured FTP or SFTP connection without saving first.
* **Update Field Roles** updates roles after changed FactFinder field mappings. By default, `Master` and `ProductNumber` hold the master article number and product number roles.

### Advanced settings

![Advanced settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/advanced-settings.png)

* **Use URL params?** adds each query parameter to the URL.
* **Additional parameters** defines `add-params`, `add-tracking-params`, `keep-url-params`, and `parameter-whitelist` request values.
* **Anonymize User ID?** sends an anonymized user ID for tracking.
* **Use Proxy** sends Web Components requests through the module controller.
* **How to count single click on Add to cart button?** controls add-to-cart counting.
* **Send the SID as userId when user not logged in?** uses the session ID for anonymous users.

### Proxy

The proxy controller forwards Web Components requests to FactFinder. It lets you customize requests and responses. You can also add fallback behavior.

```php
// src/Controller/SearchResultController.php:65
protected function fallback(): void
{
    // Add fallback logic for communication errors.
    $this->showJsonAndExit('');
}
```

Enable the proxy with rewrite rules. OXID routes AJAX requests through `index.php` using `cl` and `fnc` parameters.

{% tabs %}
{% tab title="NGINX" %}

```nginx
location ~ \.ff  {
    rewrite [a-zA-Z].ff /$1 break;
}

# Adjust the version for the API version in use.
location ~ /rest/v  {
    rewrite rest/v[0-9]/[a-zA-Z]*/ /$1 break;
}
```

{% endtab %}

{% tab title="Apache" %}

```apache
RewriteRule (.*\.ff)$ /$1 [L]

# Adjust the version for the API version in use.
RewriteRule /rest/v[0-9] /$1 [L]
```

{% endtab %}
{% endtabs %}

Without these rules, requests return `404` errors.

### Feature settings

![Feature settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/features-settings.png)

* **Use FACT-Finder® for category pages?** enables Web Components on category pages.
* **Campaigns** enables product, feedback-text, and shopping-cart campaign components.
* **Recommendations** enables `ff-recommendation` on product pages.
* **Similar products** enables `ff-similar-products` on product pages.
* **Pushed products** enables `ff-campaign-pushed-products` on cart pages.
* **Disable cache** controls search-result caches.

#### Category pages

The module preserves category URLs and SEO with standard OXID routing. It adds custom parameters to the FactFinder request. Opening a category page emits a search event.

### Feed settings

![Feed settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/feed-settings.png)

Select the attributes to export. Set **Multi-Attribute** to **No** for a separate column. Set it to **Yes** for the aggregated `FilterAttributes` column. Selection attributes always use `FilterAttributes`.

### Export settings

![Export settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/export-settings.png)

Configure the FTP or SFTP connection used for feed uploads:

* FTP host, port, user, and password
* SSL, when your FTP server requires it
* Automatic product import and the Data, Suggest, or Recommendation imports
* HTTP export basic-auth credentials
* Export log path and error-continuation behavior

Basic authentication protects HTTP exports. See [Export methods](https://docs.fact-finder.com/oxid/sdk-v6.x-sdk-v5.x/sdk-v5.x/export-methods.md) for the export URLs and workflow.


---

# 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/oxid/sdk-v6.x-sdk-v5.x/sdk-v5.x/backend-configuration.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.
