From 118fd1711fe2cdf3ad9d318c3f12d77cac86a3fe Mon Sep 17 00:00:00 2001
From: ValueOn AG <p.motsch@valueon.ch>
Date: Sun, 7 Dec 2025 23:51:31 +0100
Subject: [PATCH] rbac doc adapted

---
 appdoc/doc_security_role_based_access.md | 57 ++++++++++++++++--------
 1 file changed, 38 insertions(+), 19 deletions(-)

diff --git a/appdoc/doc_security_role_based_access.md b/appdoc/doc_security_role_based_access.md
index f68f194..e061e96 100644
--- a/appdoc/doc_security_role_based_access.md
+++ b/appdoc/doc_security_role_based_access.md
@@ -47,31 +47,50 @@ The new RBAC system implements a **matrix-based access model** with database-lev
 
 ### Frontend Options Format
 
-The `frontend_options` attribute in Field definitions supports two formats:
+The `frontend_options` attribute in Field definitions supports **two formats**:
 
-1. **Static List** (for basic data types): A list of option dictionaries
-   ```python
-   frontend_options=[
-       {"value": "a", "label": {"en": "All Records", "fr": "Tous les enregistrements"}},
-       {"value": "m", "label": {"en": "My Records", "fr": "Mes enregistrements"}}
-   ]
-   ```
+#### 1. Static List (for basic data types)
+A list of option dictionaries for static, predefined options:
+```python
+frontend_options=[
+    {"value": "a", "label": {"en": "All Records", "fr": "Tous les enregistrements"}},
+    {"value": "m", "label": {"en": "My Records", "fr": "Mes enregistrements"}}
+]
+```
 
-2. **String Reference** (for custom types): A string identifier that references dynamic options
-   ```python
-   frontend_options="user.role"  # Frontend fetches from /api/options/user.role
-   ```
+**Use static lists when:**
+- Options are fixed and don't change based on user context
+- Options are simple enums or constants
+- Options don't require database queries
 
-**Dynamic Options API**: When `frontend_options` is a string reference, the frontend must fetch options from `/api/options/{optionsName}`. This allows for:
-- Database-driven options (e.g., user connections loaded from database)
-- Context-aware options (e.g., options filtered by current user's permissions)
-- Centralized option management (e.g., role definitions managed in one place)
+#### 2. String Reference (for dynamic/custom types)
+A string identifier that references dynamic options from the Options API:
+```python
+frontend_options="user.role"  # Frontend fetches from /api/options/user.role
+```
+
+**Use string references when:**
+- Options come from the database (e.g., user connections)
+- Options are context-aware (filtered by current user's permissions)
+- Options need centralized management (e.g., role definitions)
+- Options may change frequently
+
+**Dynamic Options API**: When `frontend_options` is a string reference, the frontend must:
+1. Detect that it's a string (not a list)
+2. Fetch options from `/api/options/{optionsName}`
+3. Use the returned options for the select/multiselect field
 
 **Available Option Names**:
 - `"user.role"` - User role options (sysadmin, admin, user, viewer)
-- `"user.connection"` - User connection types
-- `"auth.authority"` - Authentication authorities
-- `"connection.status"` - Connection statuses
+- `"user.connection"` - User connection types (context-aware, requires currentUser)
+- `"auth.authority"` - Authentication authorities (local, google, msft)
+- `"connection.status"` - Connection statuses (active, inactive, expired, error)
+
+**Type Definition**: The `frontend_options` attribute is typed as `Union[List[Dict[str, Any]], str]`:
+- `List[Dict[str, Any]]`: Static list format
+- `str`: String reference format
+
+See `gateway/modules/shared/frontendOptionsTypes.py` for type definitions and utility functions.
 
 ### Access Rule Model