Skip to content

Commit 84792c1

Browse files
simonredfernsimonredfern
committed
docfix: More Glossary Items for Dynamic Entities
1 parent ed414e2 commit 84792c1

File tree

1 file changed

+183
-1
lines changed

1 file changed

+183
-1
lines changed

‎obp-api/src/main/scala/code/api/util/Glossary.scala‎

Lines changed: 183 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2826,7 +2826,7 @@ object Glossary extends MdcLoggable {
28262826

28272827

28282828
glossaryItems += GlossaryItem(
2829-
title = "Dynamic Entity Manage",
2829+
title = "Dynamic Entity Intro",
28302830
description =
28312831
s"""
28322832
|
@@ -2874,6 +2874,188 @@ object Glossary extends MdcLoggable {
28742874
| * [Introduction to Dynamic Entities](https://vimeo.com/426524451)
28752875
| * [Features of Dynamic Entities](https://vimeo.com/446465797)
28762876
|
2877+
""".stripMargin)
2878+
2879+
glossaryItems += GlossaryItem(
2880+
title = "Dynamic Entities",
2881+
description =
2882+
s"""
2883+
|
2884+
|Dynamic Entities allow you to create custom data structures and their corresponding CRUD endpoints at runtime without writing code or restarting the OBP-API instance.
2885+
|
2886+
|**Overview:**
2887+
|
2888+
|Dynamic Entities enable you to define custom business objects (entities) with their fields, types, and validation rules via API calls. Once created, OBP automatically generates fully functional REST API endpoints for Create, Read, Update, and Delete operations.
2889+
|
2890+
|**Types of Dynamic Entities:**
2891+
|
2892+
|1. **System Level Dynamic Entities** - Available across the entire OBP instance
2893+
|2. **Bank Level Dynamic Entities** - Scoped to a specific bank
2894+
|
2895+
|**Creating a Dynamic Entity:**
2896+
|
2897+
|```json
2898+
|POST /management/system-dynamic-entities
2899+
|{
2900+
| "hasPersonalEntity": true,
2901+
| "CustomerPreferences": {
2902+
| "description": "Customer preferences and settings",
2903+
| "required": ["theme"],
2904+
| "properties": {
2905+
| "theme": {
2906+
| "type": "string",
2907+
| "example": "dark"
2908+
| },
2909+
| "language": {
2910+
| "type": "string",
2911+
| "example": "en"
2912+
| },
2913+
| "notifications_enabled": {
2914+
| "type": "boolean",
2915+
| "example": true
2916+
| }
2917+
| }
2918+
| }
2919+
|}
2920+
|```
2921+
|
2922+
|**Supported field types:**
2923+
|
2924+
|STRING, INTEGER, DOUBLE, BOOLEAN, DATE_WITH_DAY (format: yyyy-MM-dd), and reference types (foreign keys)
2925+
|
2926+
|**The hasPersonalEntity flag:**
2927+
|
2928+
|When **hasPersonalEntity = true** (default):
2929+
|
2930+
|OBP generates TWO sets of endpoints:
2931+
|
2932+
|1. **Regular endpoints** - Access all entities (requires specific roles)
2933+
| * POST /CustomerPreferences
2934+
| * GET /CustomerPreferences
2935+
| * GET /CustomerPreferences/ID
2936+
| * PUT /CustomerPreferences/ID
2937+
| * DELETE /CustomerPreferences/ID
2938+
|
2939+
|2. **Personal 'my' endpoints** - User-scoped access (see ${getGlossaryItemLink("My Dynamic Entities")})
2940+
| * POST /my/CustomerPreferences
2941+
| * GET /my/CustomerPreferences
2942+
| * GET /my/CustomerPreferences/ID
2943+
| * PUT /my/CustomerPreferences/ID
2944+
| * DELETE /my/CustomerPreferences/ID
2945+
|
2946+
|When **hasPersonalEntity = false**:
2947+
|
2948+
|OBP generates ONLY the regular endpoints. No 'my' endpoints are created. Use this when the entity represents shared data that should not be user-scoped.
2949+
|
2950+
|**For bank-level entities**, endpoints include the bank ID:
2951+
|
2952+
|* POST /banks/BANK_ID/CustomerPreferences
2953+
|* POST /banks/BANK_ID/my/CustomerPreferences (if hasPersonalEntity = true)
2954+
|
2955+
|**Auto-generated roles:**
2956+
|
2957+
|When you create a Dynamic Entity named 'FooBar', OBP automatically creates these roles:
2958+
|
2959+
|* CanCreateDynamicEntity_FooBar
2960+
|* CanUpdateDynamicEntity_FooBar
2961+
|* CanGetDynamicEntity_FooBar
2962+
|* CanDeleteDynamicEntity_FooBar
2963+
|
2964+
|**Management endpoints:**
2965+
|
2966+
|* POST /management/system-dynamic-entities - Create system level entity
2967+
|* POST /management/banks/BANK_ID/dynamic-entities - Create bank level entity
2968+
|* GET /management/system-dynamic-entities - List all system level entities
2969+
|* GET /management/banks/BANK_ID/dynamic-entities - List bank level entities
2970+
|* PUT /management/system-dynamic-entities/DYNAMIC_ENTITY_ID - Update entity definition
2971+
|* DELETE /management/system-dynamic-entities/DYNAMIC_ENTITY_ID - Delete entity (and all its data)
2972+
|
2973+
|**Required roles to manage Dynamic Entities:**
2974+
|
2975+
|* CanCreateSystemLevelDynamicEntity
2976+
|* CanCreateBankLevelDynamicEntity
2977+
|
2978+
|**Use cases:**
2979+
|
2980+
|* Customer preferences and settings
2981+
|* Custom metadata for accounts or transactions
2982+
|* Business-specific data structures
2983+
|* Rapid prototyping of new features
2984+
|* Extension of core banking data model
2985+
|
2986+
|For user-scoped Dynamic Entities, see ${getGlossaryItemLink("My Dynamic Entities")}
2987+
|
2988+
|For more detailed information about managing Dynamic Entities, see ${getGlossaryItemLink("Dynamic Entity Intro")}
2989+
|
2990+
""".stripMargin)
2991+
2992+
glossaryItems += GlossaryItem(
2993+
title = "My Dynamic Entities",
2994+
description =
2995+
s"""
2996+
|
2997+
|My Dynamic Entities are user-scoped endpoints that are automatically generated when you create a Dynamic Entity with hasPersonalEntity set to true (which is the default).
2998+
|
2999+
|**How it works:**
3000+
|
3001+
|1. Create a Dynamic Entity definition (System or Bank Level) with hasPersonalEntity = true
3002+
|2. OBP automatically generates both regular CRUD endpoints AND 'my' endpoints
3003+
|3. The 'my' endpoints only return data created by the authenticated user
3004+
|
3005+
|**Example workflow:**
3006+
|
3007+
|**Step 1:** Create a Dynamic Entity definition
3008+
|
3009+
|```json
3010+
|POST /management/system-dynamic-entities
3011+
|{
3012+
| "hasPersonalEntity": true,
3013+
| "CustomerPreferences": {
3014+
| "description": "User preferences",
3015+
| "required": ["theme"],
3016+
| "properties": {
3017+
| "theme": {"type": "string"},
3018+
| "language": {"type": "string"}
3019+
| }
3020+
| }
3021+
|}
3022+
|```
3023+
|
3024+
|**Step 2:** Use the auto-generated 'my' endpoints:
3025+
|
3026+
|* POST /my/CustomerPreferences - Create my preference
3027+
|* GET /my/CustomerPreferences - Get all my preferences
3028+
|* GET /my/CustomerPreferences/ID - Get one of my preferences
3029+
|* PUT /my/CustomerPreferences/ID - Update my preference
3030+
|* DELETE /my/CustomerPreferences/ID - Delete my preference
3031+
|
3032+
|**For bank-level entities:**
3033+
|
3034+
|* POST /banks/BANK_ID/my/CustomerPreferences
3035+
|* GET /banks/BANK_ID/my/CustomerPreferences
3036+
|* GET /banks/BANK_ID/my/CustomerPreferences/ID
3037+
|* PUT /banks/BANK_ID/my/CustomerPreferences/ID
3038+
|* DELETE /banks/BANK_ID/my/CustomerPreferences/ID
3039+
|
3040+
|**Key differences:**
3041+
|
3042+
|* **Regular endpoints** (e.g., /CustomerPreferences): Access ALL entities (requires roles)
3043+
|* **My endpoints** (e.g., /my/CustomerPreferences): Access only your own entities (user-scoped)
3044+
|
3045+
|**Note:** If hasPersonalEntity is set to false, no 'my' endpoints are generated.
3046+
|
3047+
|**Management endpoints for Dynamic Entity definitions:**
3048+
|
3049+
|* GET /my/dynamic-entities - Get all Dynamic Entity definitions I created
3050+
|* PUT /my/dynamic-entities/DYNAMIC_ENTITY_ID - Update a definition I created
3051+
|
3052+
|**Required roles:**
3053+
|
3054+
|* CanCreateSystemLevelDynamicEntity - To create system level dynamic entities
3055+
|* CanCreateBankLevelDynamicEntity - To create bank level dynamic entities
3056+
|
3057+
|For general information about Dynamic Entities, see ${getGlossaryItemLink("Dynamic Entities")}
3058+
|
28773059
""".stripMargin)
28783060

28793061
glossaryItems += GlossaryItem(

0 commit comments

Comments
 (0)