---
title: "Configuration"
manual: "Context Reporter"
version: "0.1"
permalink: "https://docs.typo3.org/permalink/priebera/typo3-context-reporter:configuration@0.1"
source: "Configuration/Index.rst"
rendered: "2026-09-23T13:31:07+00:00"
---

# Configuration {#configuration}

Administrators configure Context Reporter in **System > Context
Reports**: the **Settings** button is at the top right of the report
list. The settings have the sections **General**,
**Privacy**, **Reports & storage**, **Email** and
**Webhook**. Only administrators can open them.

## Where settings are stored {#configuration-storage}

The settings of the module are stored in the TYPO3 registry (table
`sys_registry`, namespace `tx_contextreporter`), not in
`config/system/settings.php`. Each section is saved on its own; the page
shows when and by whom the settings were last saved.

Values in `$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['context_reporter']`
take precedence over the module. They are shown read-only on the settings
page. Use this to pin values per environment, for example to switch off
deliveries on a staging system that runs on a copy of the production
database:

**config/system/additional.php**

```php
if (!\TYPO3\CMS\Core\Core\Environment::getContext()->isProduction()) {
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['context_reporter']['email']['enabled'] = false;
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['context_reporter']['webhook']['enabled'] = false;
}
```

The keys are the setting names below, grouped by section, for example
`['reporting']['retentionDays']`. Each key is pinned on its own; keys that
are not set in the system configuration stay editable. The extension has no
**Extension Configuration** form.

## General {#configuration-general}

-   **general.enabled**

    -   *Type:* boolean
    -   *Default:* true

    Enables reporting for backend users. It can be disabled for individual
    users or groups with [user TSconfig](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:configuration-tsconfig@0.1).
    Stored reports remain available when reporting is disabled.

-   **general.projectName**

    -   *Type:* string
    -   *Default:* site name

    Shown in reports, email subjects and webhook payloads. When empty, the
    TYPO3 site name (`$GLOBALS['TYPO3_CONF_VARS']['SYS']['sitename']`) is
    used.

-   **general.projectIdentifier**

    -   *Type:* string
    -   *Default:* (empty)

    Optional stable key, for example `customer-portal`, that helps receiving
    systems to route reports. Up to 64 letters, digits, dots, hyphens and
    underscores.

-   **general.environment**

    -   *Type:* string
    -   *Default:* application context

    `Production`, `Staging`, `Development`, `Testing` or a custom
    name of up to 50 characters. When empty, the TYPO3 application context is
    used.

## Privacy {#configuration-privacy}

The **Privacy** section also lists what every report contains and
what it never contains, see [Allowlist first](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:privacy-allowlist@0.1).

-   **privacy.reporterUid**

    -   *Type:* boolean
    -   *Default:* true

    Share the backend user UID of the reporter. The report history uses it to
    show who reported a problem.

-   **privacy.reporterUsername**

    -   *Type:* boolean
    -   *Default:* true

    Share the username of the reporter.

-   **privacy.reporterRealName**

    -   *Type:* boolean
    -   *Default:* false

    Share the real name of the reporter.

-   **privacy.reporterEmail**

    -   *Type:* boolean
    -   *Default:* false

    Share the email address of the reporter. Required for
    [email.replyToReporter](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:confval-setting-email-replytoreporter@0.1).

-   **privacy.reporterGroups**

    -   *Type:* boolean
    -   *Default:* false

    Share the backend user groups (UID and title) and the administrator flag.

-   **privacy.browserDetails**

    -   *Type:* boolean
    -   *Default:* true

    Share browser and operating system, user agent, language, time zone,
    window and screen size, pixel ratio, color scheme and the reduced motion
    preference.

-   **privacy.recentBackendErrors**

    -   *Type:* boolean
    -   *Default:* false

    Adds up to ten error and warning entries of the reporter from the backend
    log (`sys_log`) of the last 30 minutes, shortened. Log messages can
    contain record titles, file names or other sensitive diagnostic text,
    see [Recent backend errors](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:privacy-recent-errors@0.1). Enable this only if everyone who
    receives reports may see such text.

## Reports and storage {#configuration-reporting}

-   **reporting.maxScreenshotSizeKb**

    -   *Type:* integer
    -   *Default:* 5120

    Maximum size of a screenshot in KB (100 to 15360). Larger screenshots are
    compressed in the browser, first as PNG, then as JPEG with a lower
    resolution. Screenshots are stored in the database; the limit must stay
    below the `max_allowed_packet` of MariaDB or MySQL, see
    [Storage](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:privacy-storage@0.1).

-   **reporting.maxReportsPerUserPerHour**

    -   *Type:* integer
    -   *Default:* 20

    Protects the destinations against floods (0 to 1000). `0` disables the
    limit.

-   **reporting.retentionDays**

    -   *Type:* integer
    -   *Default:* 0 (keep forever)

    How long reports, their screenshots and delivery history are kept:
    forever (`0`), 30, 90, 180 or 365 days, or a custom number of days
    (1 to 3650). Reports are only removed when an administrator runs the
    [cleanup](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:usage-retention@0.1); changing the setting removes nothing.

The section also shows how many reports, screenshots (with their size) and
delivery attempts are stored, and a preview of the cleanup. With the default
retention, the history grows with every report.

## Email {#configuration-email}

Emails are sent with the mail transport of TYPO3
(`$GLOBALS['TYPO3_CONF_VARS']['MAIL']`, **Admin Tools > Settings >
Configure Installation-Wide Options**). Context Reporter has no SMTP settings
of its own.

-   **email.enabled**

    -   *Type:* boolean
    -   *Default:* false

    Sends every report by email. Requires at least one recipient.

-   **email.recipients**

    -   *Type:* string
    -   *Default:* (empty)

    Up to 20 email addresses, separated by commas, semicolons or line breaks.

-   **email.senderAddress**

    -   *Type:* string
    -   *Default:* (empty)

    Sender address of the email. When empty, the TYPO3 default mail sender
    (`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress']`) is
    used.

-   **email.senderName**

    -   *Type:* string
    -   *Default:* (empty)

    Sender name, used together with [email.senderAddress](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:confval-setting-email-senderaddress@0.1).

-   **email.subject**

    -   *Type:* string
    -   *Default:* \[{project.name}\] {report.title} ({report.id})

    Subject with [markers](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:integration-email-markers@0.1).

-   **email.bodyTemplate**

    -   *Type:* string
    -   *Default:* EXT:context_reporter/Resources/Private/Templates/Email/Report.txt

    Plain text template with [markers](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:integration-email-markers@0.1). It
    must be a `.txt` file below `Resources/Private/` of an
    extension, for example
    `EXT:my_sitepackage/Resources/Private/Templates/Email/ContextReport.txt`.
    Other paths are rejected, so no other file of the installation can end up
    in an email.

-   **email.attachScreenshot**

    -   *Type:* boolean
    -   *Default:* true

    Attaches the screenshot.

-   **email.attachJson**

    -   *Type:* boolean
    -   *Default:* true

    Attaches the report as JSON file, without the screenshot.

-   **email.replyToReporter**

    -   *Type:* boolean
    -   *Default:* false

    Uses the reporter as Reply-To address. Only works when
    [privacy.reporterEmail](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:confval-setting-privacy-reporteremail@0.1) is enabled.

### Email status and test email {#configuration-email-status}

Next to the form, the **Status** panel explains whether reports can be
sent by email with the saved settings: whether delivery is switched on, the
recipients, the sender that is used, the TYPO3 mail transport (host and port,
sendmail binary or DSN scheme and host; credentials are never shown) and the
attachments. It warns when

-   email delivery is switched off or no recipient is configured,
-   the TYPO3 transport is `null` (emails are discarded) or `mbox`
    (emails are written to a file),
-   emails are spooled and only sent by `vendor/bin/typo3 mailer:spool:send`,
-   the transport points to a local mail catcher such as Mailpit, for example
    in DDEV projects, so emails do not reach real mailboxes,
-   no valid sender address is configured.

**Send test email** sends a short message without report data to the
saved recipients, also while email delivery is switched off. Transport errors
are shown without credentials.

> [!TIP]
> If reports do not arrive by email, check the status panel first: in most
> cases email delivery is switched off, no recipient is saved, or the
> TYPO3 mail transport is a local mail catcher or a spool.

## Webhook {#configuration-webhook}

-   **webhook.enabled**

    -   *Type:* boolean
    -   *Default:* false

    Sends every report to the webhook endpoint.

-   **webhook.url**

    -   *Type:* string
    -   *Default:* (empty)

    HTTPS endpoint that receives a JSON `POST` request. Accepts an
    [environment variable reference](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:configuration-environment@0.1). Webhook
    URLs often contain access tokens, so a stored URL is never shown again:
    the settings page only shows scheme and host. Leave the field empty to
    keep the stored URL.

-   **webhook.secret**

    -   *Type:* string
    -   *Default:* (empty)

    Signs each request with HMAC-SHA256, see
    [Verifying the signature](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:integration-webhook-signature@0.1). Accepts an
    [environment variable reference](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:configuration-environment@0.1).

-   **webhook.authHeaderName**

    -   *Type:* string
    -   *Default:* Authorization

    Name of an additional authentication header, for example `X-Api-Key`.

-   **webhook.authHeaderValue**

    -   *Type:* string
    -   *Default:* (empty)

    Value of the authentication header, for example `Bearer <token>`. The
    header is only sent when a value is set. Accepts an
    [environment variable reference](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:configuration-environment@0.1).

-   **webhook.includeScreenshot**

    -   *Type:* boolean
    -   *Default:* true

    Embeds the screenshot as base64 in the request.

-   **webhook.timeout**

    -   *Type:* integer
    -   *Default:* 10

    Timeout in seconds (1 to 30). The reporter waits for the delivery.

-   **webhook.allowInsecureHttp**

    -   *Type:* boolean
    -   *Default:* false

    Allows plain `http://` URLs. Only for local development.

The webhook is configured by trusted administrators: the endpoint can be any
host the TYPO3 server can reach. See [Webhook: trusted administrators](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:privacy-webhook-boundary@0.1) for the
consequences and how to pin the webhook settings.

The secret fields are write-only: the settings page shows whether a value is
configured, configured via an environment variable, or whether the
environment variable is missing, but never the value. Leave a field empty to
keep the stored value, or tick **Remove the stored value**.

**Send test webhook** posts the event `test` with the saved
settings, also while webhook delivery is switched off, see
[Test deliveries](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:integration-webhook-test@0.1). Test deliveries are not added to the
delivery history.

## Secrets from environment variables {#configuration-environment}

[webhook.url](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:confval-setting-webhook-url@0.1), [webhook.secret](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:confval-setting-webhook-secret@0.1) and
[webhook.authHeaderValue](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:confval-setting-webhook-authheadervalue@0.1) accept a value of the form
`%env(NAME)%`, both in the settings page and in the system configuration.
The value is read from the environment variable `NAME` when a report is
delivered, so the secret itself is not stored in the database or in a
configuration file. Settings that are entered directly are stored in
`sys_registry`; prefer environment variables for production secrets.

The resolved value is sent to the webhook endpoint, as signing key or header
value. Any environment variable of the web server process can be referenced,
so only reference variables that are meant for the webhook, and see
[Webhook: trusted administrators](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:privacy-webhook-boundary@0.1).

**config/system/additional.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['context_reporter']['webhook']['secret']
    = '%env(CONTEXT_REPORTER_WEBHOOK_SECRET)%';
```

Secrets are never shown in the backend, and they are removed from stored
error messages.

## User TSconfig {#configuration-tsconfig}

Disable reporting for a user or group:

**User TSconfig**

```typoscript
options.contextReporter.enable = 0
```

The toolbar button, the context menu item and the editing form button are
removed, and the server rejects reports from this user.

Hide the context menu item for a table (standard TYPO3 option). Files and
folders use the tables `sys_file` and `sys_file_storage`:

**User TSconfig**

```typoscript
options.contextMenu.table.tt_content.disableItems = contextReporterReport
options.contextMenu.table.sys_file.disableItems = contextReporterReport
```

The list view of the file list shows the actions of
`options.file_list.primaryActions` as buttons and all other actions in the
**More options** menu. The extension ships this user TSconfig, which is
the TYPO3 default plus the report action:

**EXT:context_reporter/Configuration/user.tsconfig**

```typoscript
options.file_list.primaryActions = view, metadata, translations, delete, contextReporterReport
```

If your project defines its own list, add `contextReporterReport` to it to
keep the action visible.

## Access {#configuration-access}

-   Every backend user can create reports, unless disabled with TSconfig.
-   A report can only reference pages and records that the reporter can
    access (web mounts, page permissions and table permissions), and files
    and folders in the reporter's file storages and file mounts, with read
    permission. File metadata can only be reported for accessible files. In
    a workspace, only live records and versions of the current workspace can
    be reported. See [Protection of reports](https://docs.typo3.org/permalink/priebera/typo3-context-reporter:privacy-protection@0.1).
-   The **System > Context Reports** module, including the settings,
    test deliveries, the cleanup and the review state, is available to
    administrators only.
-   Reporters can download their own reports.