= Technical Asset Module - Technical Documentation = == 1. Overview == The '''''Technical Asset (ITA)''''' module extends CzechIdM's identity management capabilities by introducing a new entity type that groups and manages technical accounts. This module enables organizations to associate technical accounts with specific assets, assign guarantors and managers through both direct assignment and role-based mechanisms, and implement comprehensive audit trails for all operations. === 1.1 Module Purpose === + Centralize management of technical accounts under logical asset groupings + Enable role-based access control for asset-related operations + Provide audit capabilities for compliance requirements + Support notification workflows via NOTIFY integration ---- == 2. Entity Architecture == === 2.1 Core Entities === ==== TechnicalAsset (ITA) ==== The primary entity representing a technical asset that can contain multiple technical accounts. '''''Key Attributes:''''' + id - Primary identifier + name - Asset name + description - Optional description + disabled - Flag indicating if the asset is disabled + externalId - Identifier assigned by an external system for integration purposes + externalCode - Code from an external system + validFrom - Validity start date + validTill - Validity end date '''''Special Permissions:''''' | Permission | Description | |------------|-------------| | SETTOTECHNICALACCOUNT | Allows user to assign this TechnicalAsset to a TechnicalAccount during creation or modification | ---- ==== TechnicalAssetGuarantor ==== Represents direct assignment of an identity as guarantor for a technical asset. '''''Relationships:''''' + One-to-one with Identity (guaranteed person) + Many-to-one with TechnicalAsset ---- ==== TechnicalAssetGuarantorRole ==== Enables role-based guarantor assignment - users assigned this role become automatic guarantors of the associated asset. '''''Relationships:''''' + Many-to-one with Role + Many-to-one with TechnicalAsset ---- ==== TechnicalAssetManager ==== Represents direct assignment of an identity as manager (disponent) for a technical asset. '''''Relationships:''''' + One-to-one with Identity (managing person) + Many-to-one with TechnicalAsset ---- ==== TechnicalAssetManagerRole ==== Enables role-based manager assignment - users assigned this role become automatic managers of the associated asset. '''''Relationships:''''' + Many-to-one with Role + Many-to-one with TechnicalAsset ---- === 2.2 Entity Relationships Diagram === ┌─────────────────────┐ ┌─────────────────────┐ │ TechnicalAccount │◄───┐ │ TechnicalAsset │ └─────────────────────┘ │ └─────────────────────┘ │ │ │ │ │ ├──► TechnicalAssetGuarantor │ │ │ (direct) │ │ │ │ │ ├──► TechnicalAssetManager │ │ (direct) │ │ │ ├──► TechnicalAssetGuarantorRole │ │ (role-based) │ │ │ └──► TechnicalAssetManagerRole │ (role-based) │ └─────────────┐ │ [technicalAsset] ---- == 3. Database Schema == === 3.1 Migration File === '''''File:''''' V15''02''001__tech-asset.sql Creates the following tables: | Table | Description | |-------|-------------| | idm''technical''asset | Core asset entity with audit columns | | idm''technical''asset_audit | Audit history for assets | | idm''technical''asset_guarantor | Direct guarantor assignments | | idm''technical''asset''guarantor''audit | Audit history for guarantors | | idm''technical''asset''guarantor''role | Role-based guarantor assignments | | idm''technical''asset''guarantor''role_audit | Audit history for guarantor roles | | idm''technical''asset_manager | Direct manager assignments | | idm''technical''asset''manager''audit | Audit history for managers | | idm''technical''asset''manager''role | Role-based manager assignments | | idm''technical''asset''manager''role_audit | Audit history for manager roles | ---- == 4. API Endpoints == === 4.1 TechnicalAsset Controller === '''''Base Path:''''' /api/technical-assets | Method | Endpoint | Description | Required Permission | |--------|----------|-------------|---------------------| | GET | / | List all assets with filtering | READ | | POST | / | Create new asset | CREATE | | GET | /{id} | Get single asset by ID | READ | | PUT | /{id} | Update existing asset | UPDATE | | DELETE | /{id} | Delete asset | DELETE | | GET | /count | Count assets matching filter | COUNT | | GET | /autocomplete | Autocomplete suggestions | AUTOCOMPLETE | === 4.2 TechnicalAssetGuarantor Controller === '''''Base Path:''''' /api/technical-assets/guarantors Standard CRUD operations for direct guarantor assignments. === 4.3 TechnicalAssetGuarantorRole Controller === '''''Base Path:''''' /api/technical-assets/guarantor-roles Standard CRUD operations for role-based guarantor assignments. === 4.4 TechnicalAssetManager Controller === '''''Base Path:''''' /api/technical-assets/managers Standard CRUD operations for direct manager assignments. === 4.5 TechnicalAssetManagerRole Controller === '''''Base Path:''''' /api/technical-assets/manager-roles Standard CRUD operations for role-based manager assignments. ---- == 5. Permission Model == === 5.1 Standard Permissions (All Entities) === IdmBasePermission.ADMIN, IdmBasePermission.COUNT, IdmBasePermission.AUTOCOMPLETE, IdmBasePermission.READ, IdmBasePermission.CREATE, IdmBasePermission.UPDATE, IdmBasePermission.DELETE === 5.2 Special Permission - SETTOTECHNICALACCOUNT === '''''Defined in:''''' TechnicalAssetBasePermission.java This permission is required when: + Creating a TechnicalAccount with an associated TechnicalAsset + Modifying a TechnicalAccount to add/change its TechnicalAsset association '''''Use Case Example:''''' // User must have SETTOTECHNICALACCOUNT on the target TechnicalAsset technicalAccount.setTechnicalAsset(asset); // Requires permission check === 5.3 Related Entity Permissions === Guarantors and Managers require '''''UPDATE''''' permission on TechnicalAsset to create related entities (guarantor/manager assignments) for that asset. ---- == 6. Event Processing Architecture == All entities implement the Eventable interface, triggering event processors on save/delete operations. === 6.1 TechnicalAsset Processors === ==== TechnicalAssetSaveProcessor ==== + Triggers on entity creation/update + Initiates NOTIFY line startup process + Updates related audit records ==== TechnicalAssetDeleteProcessor ==== + Handles cleanup of associated resources + Notifies dependent systems via NOTIFY integration ==== TechnicalAssetPublishChangeProcessor ==== + Publishes change events for external consumers + Supports real-time synchronization requirements === 6.2 Related Entity Processors === Each related entity has dedicated save/delete processors: | Processor | Purpose | |-----------|---------| | TechnicalAssetGuarantorSaveProcessor | Handles guarantor assignment events | | TechnicalAssetGuarantorDeleteProcessor | Handles guarantor removal events | | TechnicalAssetGuarantorRoleSaveProcessor | Handles role-based guarantor events | | TechnicalAssetGuarantorRoleDeleteProcessor | Handles role-based guarantor removal | | TechnicalAssetManagerSaveProcessor | Handles manager assignment events | | TechnicalAssetManagerDeleteProcessor | Handles manager removal events | | TechnicalAssetManagerRoleSaveProcessor | Handles role-based manager events | | TechnicalAssetManagerRoleDeleteProcessor | Handles role-based manager removal | ---- == 7. Service Layer Architecture == === 7.1 Service Interfaces (API Contracts) === Located in: model/service/api/ public interface TechnicalAssetService { List findAll(TechnicalAssetFilter filter); TechnicalAsset findById(UUID id); TechnicalAsset create(TechnicalAsset entity); TechnicalAsset update(TechnicalAsset entity); void delete(UUID id); long count(TechnicalAssetFilter filter); } === 7.2 Default Implementations === Located in: model/service/ All services follow the pattern: Default[EntityName]Service.java '''''Key Features:''''' + Transaction management via Spring's @Transactional + Permission validation before operations + Event publishing for audit trails + Filter-based querying support ---- == 8. Testing Strategy == === 8.1 Service Layer Tests === Each service has dedicated test class covering: + CRUD operations (Create, Read, Update, Delete) + Filtering functionality + Permission enforcement + Edge cases and validation '''''Test Files:''''' DefaultTechnicalAssetServiceTest.java DefaultTechnicalAssetGuarantorServiceTest.java DefaultTechnicalAssetGuarantorRoleServiceTest.java DefaultTechnicalAssetManagerServiceTest.java DefaultTechnicalAssetManagerRoleServiceTest.java === 8.2 Controller Tests === REST endpoint tests covering: + HTTP method validation (GET, POST, PUT, DELETE) + Status code verification + Request/response payload validation + Authentication/authorization checks '''''Test Files:''''' TechnicalAssetControllerTest.java TechnicalAssetGuarantorControllerTest.java TechnicalAssetGuarantorRoleControllerTest.java TechnicalAssetManagerControllerTest.java TechnicalAssetManagerRoleControllerTest.java === 8.3 Security/Permission Tests === Tests verifying related entity permission requirements: | Test File | Validates | |-----------|-----------| | TechAccountTechAssetFixTest.java | SETTOTECHNICALACCOUNT permission for TechnicalAccount-TechnicalAsset association | | TechAssetGuarantorRoleTechAssetFixTest.java | UPDATE permission requirement for guarantor role creation | | TechAssetGuarantorTechAssetFixTest.java | UPDATE permission requirement for direct guarantor creation | | TechAssetManagerRoleTechAssetFixTest.java | UPDATE permission requirement for manager role creation | | TechAssetManagerTechAssetFixTest.java | UPDATE permission requirement for direct manager creation | ---- == 9. Integration Points == === 9.1 TechnicalAccount Integration === '''''Modified Entity:''''' TechnicalAccount.java Added optional attribute: @ManyToOne(fetch = FetchType.LAZY) private TechnicalAsset technicalAsset; This allows each technical account to be optionally associated with a technical asset for organizational purposes. === 9.2 NOTIFY Integration === The TechnicalAssetSaveProcessor initiates NOTIFY line startup, enabling real-time notifications when assets are created or modified. ---- == 10. Audit Trail == All entities implement comprehensive audit functionality: + Automatic tracking of create/update/delete operations + User attribution for all changes + Timestamp recording for compliance requirements + Separate audit tables for each entity type '''''Audit Columns (Standard):''''' | Column | Description | |--------|-------------| | created_by | Identity who created the record | | created_at | Creation timestamp | | updated_by | Identity who last modified the record | | updated_at | Last modification timestamp | ---- == 11. File Structure Summary == === New Files Created: **52 files** === ==== Domain Layer (1 file) ==== + TechnicalAssetBasePermission.java - Custom permission definitions ==== Event Processors (14 files) ==== + Save/Delete processors for all 7 entities ==== Model Layer (30 files) ==== + Entities (6 files) + DTOs (5 files) + Filters (5 files) + Repositories (5 files) + Service APIs (5 files) + Service Implementations (5 files) ==== REST Controllers (5 files) ==== + One controller per entity type ==== Database Migration (1 file) ==== + V15''02''001__tech-asset.sql - PostgreSQL migration ==== Test Files (11 files) ==== + 5 service tests + 5 controller tests + 1 security test helper modifications === Modified Files: **8 files** === TechGroupPermission.java - Permission updates TechnicalAccountDto.java - Added technicalAsset field TechnicalAccount.java - Added technicalAsset relationship TechnicalAccountFilter.java - Filter support for asset association DefaultTechnicalAccountService.java - Service logic updates DefaultTechTestHelper.java - Test helper modifications DefaultTechnicalAccountServiceTest.java - Updated tests ---- == 12. Usage Examples == === 12.1 Creating a Technical Asset with Guarantor and Manager === // Create asset TechnicalAsset asset = new TechnicalAsset(); asset.setName("Production Database Server"); asset.setDescription("Primary production database"); technicalAssetService.create(asset); // Assign direct guarantor TechnicalAssetGuarantor guarantor = new TechnicalAssetGuarantor(); guarantor.setTechnicalAsset(asset); guarantor.setIdentity(guarantorIdentity); technicalAssetGuarantorService.create(guarantor); // Assign role-based manager TechnicalAssetManagerRole managerRole = new TechnicalAssetManagerRole(); managerRole.setTechnicalAsset(asset); managerRole.setRole(managerRoleEntity); technicalAssetManagerRoleService.create(managerRole); === 12.2 Associating Technical Account with Asset === // User must have SETTOTECHNICALACCOUNT permission on the asset TechnicalAccount account = new TechnicalAccount(); account.setUsername("db-admin"); account.setTechnicalAsset(asset); // Permission check occurs here technicalAccountService.create(account); ---- == 13. Security Considerations == === 13.1 Permission Hierarchy === ADMIN (highest) ├── CREATE ├── UPDATE ├── DELETE ├── READ ├── COUNT └── AUTOCOMPLETE └── SETTOTECHNICALACCOUNT (special, asset-specific) === 13.2 Related Entity Access Control === + Creating guarantor/manager assignments requires '''''UPDATE''''' on the parent TechnicalAsset + This ensures only authorized users can modify asset relationships + Role-based assignments follow the same permission model as direct assignments ---- == 14. Future Enhancements (Recommendations) == = **Bulk Operations**: Add batch endpoints for mass asset/account associations = = **Inheritance Support**: Consider allowing assets to inherit permissions from parent organizational units = = **Lifecycle Management**: Implement state machine for asset lifecycle (draft → active → archived) = = **Notification Templates**: Extend NOTIFY integration with customizable templates per operation type = ----