Payload Preferences Blueprint

Per-user preferences storage for admin UI state including collapsed fields, tab positions, column visibility, sort order, and list view settings

   
Feature payload-preferences
Category Data
Version 1.0.0
Tags cms, preferences, user-settings, ui-state, personalization, admin-panel, payload
YAML Source View on GitHub
JSON API payload-preferences.json

Actors

ID Name Type Description
admin_user Admin User human Authenticated user whose UI preferences are stored
admin_panel Admin Panel system Payload admin UI that reads and writes preferences

Fields

Name Type Required Label Description
user json Yes Preference Owner  
key text Yes Preference Key  
value json Yes Preference Value  

Rules

  • data:
    • key_value_storage: true
    • composite_key: user + key
    • preference_types:
      • collapsed_fields: string array of collapsed field paths
      • tab_indices: array of {path: tabIndex} objects
      • field_state: {collapsed: string[], tabIndex: number} per field
      • document_preferences: {fields: {[key]: fieldState}}
      • column_preferences: [{accessor, active}] for list view columns
      • collection_preferences:
        • columns: column visibility and order
        • edit_view_type: ‘default’ ‘live-preview’
        • group_by: field to group list by
        • limit: items per page
        • list_view_type: ‘folders’ ‘list’
        • preset: saved query preset ID
        • sort: sort field
  • access:
    • per_user_isolation: true
    • hidden_from_admin: true

Outcomes

Preference_isolation (Priority: 1)

Given:

  • user attempts to access another user’s preferences

Result: Empty result returned — access silently denied through WHERE clause filtering

Get_preference (Priority: 10)

Given:

  • user is authenticated
  • key (input) exists

Then:

  • query filtered to current user’s preferences only

Result: Preference value returned for the given key, or null if not set

Set_preference (Priority: 10)

Given:

  • user is authenticated
  • key (input) exists
  • value (input) exists

Then:

  • user field auto-set from req.user via beforeValidate hook
  • set_field target: value value: provided JSON value — Upsert preference — create or update

Result: Preference saved for the current user

Delete_preference (Priority: 10)

Given:

  • user is authenticated
  • key (input) exists

Then:

  • delete_record target: preference entry — Remove preference for current user and key

Result: Preference deleted

Errors

Code Status Message Retry
PREFERENCE_VALIDATION_ERROR 400 The preference value did not pass validation Yes

Events

Event Description Payload
preference.updated Emitted when a user preference is created or updated user_id, key, timestamp
Feature Relationship Reason
payload-auth required Preferences are per-user — requires authentication to identify the user
payload-collections required Preferences stored in the auto-created payload-preferences collection

AGI Readiness

Goals

Reliable Payload Preferences

Per-user preferences storage for admin UI state including collapsed fields, tab positions, column visibility, sort order, and list view settings

Success Metrics:

Metric Target Measurement
data_accuracy 100% Records matching source of truth
duplicate_rate 0% Duplicate records detected post-creation

Constraints:

  • performance (non-negotiable): Data consistency must be maintained across concurrent operations

Autonomy

Level: supervised

Human Checkpoints:

  • before permanently deleting records

Escalation Triggers:

  • error_rate > 5

Tradeoffs

Prefer Over Reason
data_integrity performance data consistency must be maintained across all operations

Coordination

Protocol: orchestrated

Consumes:

Capability From Fallback
payload_auth payload-auth degrade
payload_collections payload-collections degrade

Safety

Action Permission Cooldown Max Auto
get_preference autonomous - -
set_preference autonomous - -
delete_preference human_required - -
preference_isolation autonomous - -
Extensions (framework-specific hints) ```yaml tech_stack: language: TypeScript framework: Payload CMS 3.x database: Multi-adapter (MongoDB, PostgreSQL, SQLite, D1) rest_endpoints: - method: GET path: /api/_preferences/:key operation: findOne - method: POST path: /api/_preferences/:key operation: update - method: DELETE path: /api/_preferences/:key operation: delete auto_created_entities: - name: payload-preferences type: collection description: Hidden system collection storing per-user preferences hidden: true ```