Presets

The Presets API provides a hierarchical configuration management system that allows users to store, retrieve, and manage application settings at different scope levels.

System Architecture

Hierarchical Scope Levels

The presets system operates on three hierarchical levels, ordered from most specific to most general:

1. User Level (User): Personal presets visible only to the individual user

2. Resource Level (Resource): Resource-specific presets visible to all users with access to the resource (e.g., document sets, projects)

3. Platform Level (Platform): System-wide presets visible to all users in the platform

Scope Resolution

When retrieving presets, the system follows a hierarchical resolution order:

• User-level presets take precedence over resource-level presets

• Resource-level presets take precedence over platform-level presets

• If collapse=true is specified, only the first default preset found in the hierarchy is returned

Default Presets

Each scope level can have one default preset per key. Default presets are automatically applied when no specific preset is selected by the user.

Permission Model

• User Level: Users can create, read, update, and delete their own presets

• Resource/Platform Levels: Require management permissions for create, update, delete, and promotion operations

• Promotion: Moving presets to higher levels requires management permissions

Content Validation

All preset content must be valid JSON. The system automatically:

• Validates JSON syntax on create/update

• Minifies JSON content for storage efficiency

Common Patterns

Typical Workflow

1. Retrieve existing presets using the get multiple presets endpoint

2. Create new presets or update existing ones based on user requirements

3. Set defaults to establish baseline configurations for scope levels

4. Promote presets from user level to resource/platform level for broader sharing

Error Handling

Operations may result in errors for various scenarios such as invalid parameters, permission failures, or validation errors.

Batch Operations

The API supports batch operations for efficiency:

• Multiple presets can be retrieved in a single request

• Multiple presets can be deleted in a single request

Data Model

PresetModel

• id: Unique identifier (string)

• name: Display name (string)

• desc: Optional description (string)

• level: Hierarchy level (User|Resource|Platform)

• entityId: Associated entity ID (null for Platform level)

• content: JSON configuration data (string)

• date: Creation/modification timestamp

• isDefault: Default flag for the scope level

Scope Object

All endpoints require a scope object that defines the resource context and access permissions for the operation.