UXPROD-2708 - Implementing a Locking Mechanism for Mapping Profiles

Summary

This document outlines the use cases and proposed design for implementing a locking mechanism within the Mapping Profile Management Interface. The primary goal is to allow authorized users to lock and unlock mapping profiles to prevent unauthorized edits or deletions, especially when profiles are in active use. This mechanism enhances data integrity and ensures that critical profiles remain consistent during export operations.

Introduction

The Mapping Profile Management Interface is a critical component that allows users to create, edit, and manage mapping profiles used in data export operations. To enhance data integrity and prevent unauthorized changes, especially when profiles are actively in use, a locking mechanism is proposed. This mechanism enables authorized users to lock a mapping profile, thereby preventing edits or deletions by other users until it is unlocked by someone with the appropriate permissions.

Use Cases

Use Case 1: Lock a Mapping Profile

Actors: User with data-export.mapping-profiles.item.lock.execute permission.

Preconditions:

• The user has access to the Mapping Profile Management Interface.

• The mapping profile is currently unlocked.

Trigger:

• The user selects the option to lock a mapping profile.

Steps:

1. Initiate Lock Action:

   • The user selects the "Lock" option on the desired mapping profile.

2. Retrieve Current Status:

   • The system retrieves the profile’s current locked status.

3. Verify Unlock Status:

   • The system checks that the profile is not already locked.

4. Update Profile Status:

   • Sets the locked field to true.

   • Assigns lockedBy to the user's ID.

   • Records the current timestamp in lockedAt.

5. Save Updated Profile:

   • The system saves the updated profile to the database.

6. Provide Confirmation:

   • The user receives a confirmation message stating the profile has been locked.

Postconditions:

• The profile is locked, and its status reflects the lock in the system.

• A lock indicator is displayed next to the profile in the UI.

• Other users are prevented from editing or deleting the profile.

Exceptions:

• Profile Already Locked:

  • If the profile is already locked, the system returns an error message: “Profile is already locked.” DB optimistic locking should be leveraged.

Use Case 2: Unlock a Mapping Profile

Actors: User with data-export.mapping-profiles.item.unlock.execute permission.

Preconditions:

• The user has access to the Mapping Profile Management Interface.

• The mapping profile is currently locked.

Trigger:

• The user selects the option to unlock a locked mapping profile.

Steps:

1. Initiate Unlock Action:

   • The user selects the "Unlock" option on the desired mapping profile.

2. Verify Unlock Permission:

   • The system verifies that the user has the data-export.mapping-profiles.item.unlock.execute permission.

3. Retrieve Current Status:

   • The system retrieves the profile’s locked status.

4. Update Profile Status:

   • Sets the locked field to false.

   • Clears lockedBy and lockedAt fields.

5. Save Updated Profile:

   • The system saves the updated profile to the database.

6. Provide Confirmation:

   • The user receives a confirmation message stating the profile has been unlocked.

Postconditions:

• The profile is unlocked, and its status reflects the unlock in the system.

• The lock indicator is removed from the profile in the UI.

• Users with appropriate permissions can now edit or delete the profile.

Exceptions:

• Profile Already Unlocked:

  • If the profile is already unlocked, the system returns an error message: “Profile is already unlocked.” DB optimistic locking should be leveraged.

Use Case 3: Edit/Delete a Locked Mapping Profile

Actors: Any user attempting to edit or delete a locked profile.

Preconditions:

• The mapping profile is locked.

Trigger:

• The user attempts to edit or delete a locked mapping profile.

Steps:

1. Attempt to Edit/Delete:

   • The user initiates an edit or delete action on the locked profile.

2. Retrieve Locked Status:

   • The system retrieves the profile’s locked status.

3. Reject Operation:

   • The system detects the profile is locked and rejects the operation.

4. Display Error Message:

   • The system displays an error message: “This profile is locked. Please unlock the profile to proceed with editing/deletion.”

Postconditions:

• The user is prevented from editing or deleting the locked profile.

• The profile remains unchanged in the system.

Exceptions:

• None.

Use Case 4: Delete an Unlocked Mapping Profile with Associated Data

Actors: User with data-export.mapping-profiles.item.delete permission.

Preconditions:

• The mapping profile is unlocked.

• The profile has associated job profiles and export files.

Trigger:

• The user selects the option to delete an unlocked mapping profile.

Steps:

1. Initiate Delete Action:

   • The user selects the "Delete" option on the unlocked mapping profile.

2. Verify Unlock Status:

   • The system verifies that the profile is not locked.

3. Retrieve Associated Data:

   • The system retrieves associated job profiles and related entities (export jobs, errors, file metadata, etc.).

4. Initiate Cascade Deletion:

   • The system initiates cascade deletion for associated job profiles and related entities.

5. Delete Export Files:

   • The system initiates the deletion of export files stored in cloud storage.

6. Delete Mapping Profile:

   • The system deletes the mapping profile from the database.

7. Provide Confirmation:

   • The user receives a confirmation message stating the profile and related data have been deleted.

Postconditions:

• The mapping profile and all associated data are removed from the system.

• Export files are deleted from cloud storage.

• No orphaned records remain in the database.

Exceptions:

• Profile Locked:

  • If the profile is locked, the system returns an error message: “Locked profiles cannot be deleted.”

Use Case 5: Edit an Unlocked Mapping Profile

Actors: User with data-export.mapping-profiles.item.edit permission.

Preconditions:

• The mapping profile is unlocked.

• The user has the necessary permission to edit mapping profiles.

Trigger:

• The user selects the option to edit an unlocked mapping profile.

Steps:

1. Navigate to Profile:

   • The user navigates to the profile management interface and selects the desired profile.

2. Verify Unlock Status:

   • The system retrieves the profile’s locked status and confirms it is unlocked.

3. Modify Profile Details:

   • The user modifies the profile details as needed.

4. Submit Changes:

   • The user submits the changes.

5. Validate Data:

   • The system validates the updated data for required fields, correct formats, and constraints.

6. Handle Concurrent Locks:

   • Before saving, the system checks if the profile has been locked by another user since the edit began. DB optimistic locking should be leveraged.

7. Save Updated Profile:

   • If unlocked, the system saves the updated profile to the database.

8. Provide Confirmation:

   • The user receives a confirmation message stating the profile has been successfully edited.

Postconditions:

• The mapping profile is updated with the new values.

• Changes are reflected in the system and visible to other users.

Exceptions:

• Data Validation Failure:

  • If validation fails, the system returns an error message specifying the issue; the profile is not saved.

• Profile Lock State Change:

  • If another user locks the profile before the edit is saved, the system prevents the edit from being completed and displays an error message: “This profile has been locked and cannot be edited.” DB optimistic locking should be leveraged.

Proposed Solution

To implement the locking mechanism effectively, several modifications are required across different layers of the application.

1. Data Structure Modifications

Add Fields to MappingProfile Entity:

• locked (boolean):

  • Type: Boolean

  • Default Value: false

  • Purpose: Indicates whether the profile is locked.

• lockedBy (UUID):

  • Type: User ID (UUID)

  • Purpose: Stores the ID of the user who locked the profile for tracking purposes.

• lockedAt (timestamp):

  • Type: Timestamp

  • Purpose: Records the date and time when the profile was locked.

Benefits:

• Persistent State Management:

  • Allows the system to persistently track the lock status of each profile.

• Auditing and Accountability:

  • Facilitates auditing by recording who locked the profile and when.

2. Service Layer Modifications

Implement Locking Logic in MappingProfileService:

• New Methods:

  • void lockProfile(UUID mappingProfileId)

  • void unlockProfile(UUID mappingProfileId)

    • Unlocking requires special permissions.

• Modified Methods:

  • void deleteMappingProfileById(UUID mappingProfileId)

  • void putMappingProfile(UUID mappingProfileId, MappingProfile mappingProfile)

Implementation Details:

• Service-Level Checks:

  • Before performing modification or deletion operations, check if the profile is unlocked.

  • If locked, throw an exception with an appropriate error message.

Optimistic Locking:

• Concurrency Handling:

  • Implement an optimistic locking mechanism to detect and prevent conflicts when multiple users attempt to edit the same profile.

  • Use versioning or timestamp checks during save operations.

3. Controller Layer Modifications

Extend API Endpoints:

• New Endpoints:

  • POST /mappingProfiles/{id}/lock

    • Description: Locks a mapping profile.

    • Permissions Required: data-export.mapping-profiles.item.lock.execute

  • POST /mappingProfiles/{id}/unlock

    • Description: Unlocks a mapping profile.

    • Permissions Required: data-export.mapping-profiles.item.unlock.execute

Implementation Details:

• Request Validation:

  • Validate that the mapping profile ID exists and that the user has the necessary permissions.

• Response Handling:

  • Return appropriate HTTP status codes (e.g., 200 OK, 400 Bad Request, 403 Forbidden).

  • Provide meaningful error messages in the response body.

4. Permissions and Role Management

Define New Permissions:

• data-export.mapping-profiles.item.lock.execute:

  • Allows Users To: Lock a mapping profile.

• data-export.mapping-profiles.item.unlock.execute:

  • Allows Users To: Unlock a mapping profile.

Access Control Considerations:

• Locking Profiles:

  • Assign the lock.execute permission to users who need to secure profiles.

• Unlocking Profiles:

  • Restrict the unlock.execute permission to administrators or supervisors.

• Role Updates:

  • Update existing roles (Eureka default roles) or create new roles to include these permissions as appropriate if needed.

5. Cascade/Relationship Management

Cascade Delete Behavior:

• Associated Job Profiles:

  • When a mapping profile is deleted, automatically delete associated job profiles.

• Related Entities:

  • Ensure that export jobs, errors, and other entities linked to job profiles are also deleted.

Export File Handling:

• External Storage Deletion:

  • Implement functionality to delete export files stored in cloud storage.

• Metadata Cleanup:

  • Remove metadata records from the database when associated job profiles are deleted.

Implementation Details:

• Service Cleanup Routine:

  • Extend MappingProfileService to initiate cleanup operations for all related data.

6. Frontend/UI Considerations

User Interface Updates:

• Lock/Unlock Options:

  • Display lock and unlock options based on the user's permissions.

• Lock Indicators:

  • Show a lock icon or visual indicator next to locked profiles.

• Action Restrictions:

  • Disable or hide edit and delete buttons for locked profiles.

User Feedback:

• Confirmation Messages:

  • Provide success messages upon locking or unlocking a profile.

• Error Messages:

  • Display error messages when a user attempts unauthorized actions on a locked profile.

• Optimistic Locking Notifications:

  • Inform users if a profile becomes locked during their editing session.

Conclusion

Implementing a locking mechanism for mapping profiles significantly enhances the security and integrity of the Mapping Profile Management Interface. By preventing unauthorized edits or deletions of critical profiles, especially during active use, the system maintains consistent and reliable export operations.

The proposed solution includes necessary modifications at the data structure, service layer, controller layer, permissions, cascade management, and frontend/UI levels. It ensures that only authorized users can lock or unlock profiles and that all associated data is appropriately managed during delete operations.

By integrating these changes, the system will provide a robust and user-friendly locking mechanism that aligns with organizational security policies and user needs.