Settings

Manage user-specific report view settings and preferences.

Overview

User settings allow each user to customize their view of a report without affecting other users. Settings are stored per user, per report and include view preferences, column visibility, sort orders, and other UI state.

GET /api/reports/{id}/settings

Get the current user's settings for a report.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Response:

{
  "settings": {
    "columns": ["name", "value", "date"],
    "sortBy": "date",
    "sortDir": "desc",
    "filters": {},
    "viewMode": "table"
  },
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/settings" },
    "inf:restore": { "href": "/api/reports/team:sales-dashboard/settings/_restore" }
  }
}

Default Behavior:

Returns an empty object {} if no settings have been saved.

Use Case:

Load user-specific view preferences when opening a report.

---

PUT /api/reports/{id}/settings

Save or update the current user's settings for a report.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Request Body:

{
  "columns": ["name", "value", "date"],
  "sortBy": "date",
  "sortDir": "desc",
  "filters": {
    "region": "West"
  },
  "viewMode": "chart",
  "customProperty": "any-value"
}

Response:

Returns the saved settings object:

{
  "columns": ["name", "value", "date"],
  "sortBy": "date",
  "sortDir": "desc",
  "filters": {
    "region": "West"
  },
  "viewMode": "chart",
  "customProperty": "any-value",
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/settings" },
    "inf:restore": { "href": "/api/reports/team:sales-dashboard/settings/_restore" }
  }
}

Behavior:

• Creates a new UserSettings entry if none exists
• Updates existing settings if already present
• Settings are scoped to the current user and report
• Replaces all settings (not merged)

Use Case:

Persist user view preferences when they make changes to report display.

---

POST /api/reports/{id}/settings/_restore

Delete the current user's settings, restoring defaults.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Response:

204 No Content on success.

Behavior:

• Removes the user's settings entry for this report
• Next GET will return empty object (defaults)
• Does not affect other users' settings

Use Case:

Reset report view to system defaults.

---

Settings Structure

Settings are free-form JSON objects that can contain any properties. Common patterns include:

View Configuration

{
  "viewMode": "table",
  "layout": "grid",
  "theme": "dark"
}

Column Management

{
  "columns": ["id", "name", "status"],
  "columnWidths": {
    "id": 100,
    "name": 200,
    "status": 150
  },
  "hiddenColumns": ["internal_id"]
}

Sorting & Filtering

{
  "sortBy": "createdAt",
  "sortDir": "desc",
  "filters": {
    "status": "active",
    "region": ["West", "East"]
  }
}

Pagination

{
  "pageSize": 50,
  "currentPage": 1
}

Settings vs Report Definition

User settings are for personal preferences (sort order, visible columns, UI state), while the report definition (defn) contains the actual report structure (visuals, datasets, layout). Settings don't affect other users or the published report.

---

Lifecycle Notes

• Settings are automatically deleted when a draft is committed (via POST /api/reports/\{id\}/draft/_commit)
• This ensures all users see the updated report with fresh defaults after structural changes
• Users can re-save their preferences after viewing the updated report