Report an Issue: In-App Reporting

dotCMS admins can now submit bug reports directly from the admin interface without leaving the platform. A new "Report an Issue" option in the toolbar's user menu opens a simple dialog where users describe the problem and optionally attach a screenshot. The report is forwarded server-side to dotCMS's issue tracking system — no credentials are ever exposed to the browser.

How to Use It#

---

1. While logged into the dotCMS admin, click your user avatar or name in the top toolbar.

2. Select "Report an Issue" from the dropdown menu.

   

3. In the dialog that opens, fill in a description of the problem (required).

4. Optionally: Attach a screenshot (PNG, JPEG, or WebP — up to 10 MB).

5. Optionally: You may select a checkbox to anonymize your report, and omit personally identifiable information (PII).

6. Click Submit. A success or error message will appear inline in the dialog.

The dialog resets when you close and reopen it, so each submission starts fresh.

What Gets Sent#

---

When you submit a report, dotCMS automatically enriches it with contextual metadata to help with diagnosis:

• dotCMS version and build number
• Your browser's user agent string
• The URL you were viewing when you opened the dialog
• Server name and timestamp
• Your user account details (see the Privacy section below)

All metadata is derived server-side. Any fields you provide in the form are namespaced under metadata.client so they cannot override system-derived fields.

Privacy & PII Controls#

---

By default, user identity information (user ID, email address, full name) is included with each report. Operators can change this behavior using the DOT_REPORT_ISSUE_INCLUDE_USER_PII configuration property:

• true (default): User account details are attached to the report.
• false: Reports are submitted anonymously — user account details are omitted and a hint is shown in the UI to let the submitter know.

This can also be controlled at the time of submission through the "anonymous" checkbox.

Enabling the Feature Flag#

---

The "Report an Issue" menu item is disabled by default and controlled by a feature flag. To make it visible to admin users, set the following in your dotCMS configuration:

DOT_FEATURE_FLAG_REPORT_ISSUE_ENABLED=true

When the flag is false or unset, the menu item simply does not appear in the toolbar. No other behavior is affected.

Backend Configuration#

---

To route submitted reports to a specific upstream dotCMS instance, set the following environment variable:

REPORT_ISSUE_WORKFLOW_URL=<url-of-your-upstream-dotcms-instance>

Cross-environment authentication is handled via the dotCMS User Proxy plugin, so upstream credentials are never exposed to the browser or to submitting users.

API Reference#

---

A new REST endpoint handles and validates report submissions:

POST /api/v1/report-issue

Accepts a multipart request with the following fields:

The OpenAPI spec has been updated to document this endpoint and all its error responses.