/
UXPROD-2708 - Implementing a Locking Mechanism for Mapping and Job Profiles

UXPROD-2708 - Implementing a Locking Mechanism for Mapping and Job Profiles

Summary

This document outlines the use cases and proposed design for implementing a locking mechanism within the Mapping and Job Profiles 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 and Job Profiles 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/Job Profile

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

Preconditions:

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

  • The mapping/job profile is currently unlocked.

Trigger:

  • The user selects the option to lock a mapping/job 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/Job Profile

Actors: User with data-export.mapping-profiles.item.unlock.execut/data-export.job-profiles.item.unlock.executee permission.

Preconditions:

  • The user has access to the Mapping/Job 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/data-export.job-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/Job Profile

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

Preconditions:

  • The mapping/job profile is locked.

Trigger:

  • The user attempts to edit or delete a locked mapping/job 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 / Job Profile

Actors: User with data-export.mapping-profiles.item.delet/data-export.job-profiles.item.deletee permission.

Preconditions:

  • The mapping/job profile is unlocked.

  • The mapping 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 for mapping profiles.

    • Job profile can be deleted without cascade operations (by current design).

  5. Delete Export Files:

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

  6. Delete Mapping/Job 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/data-export.job-profiles.item.edit permission.

Preconditions:

  • The mapping/job 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.

Add Fields to JobProfile 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 mapping/job 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)

Implement JobProfileService and implement Locking Logic in it:

  • Methods should be moved from JobProfileController to created JobProfileService:

    • void deleteJobProfileById(UUID jobProfileId)

    • JobProfile getJobProfileById(UUID jobProfileId)

    • JobProfileCollection getJobProfiles(Boolean used, String query, Integer offset, Integer limit)

    • JobProfile postJobProfile(JobProfile jobProfile)

    • void putJobProfile(UUID jobProfileId, JobProfile jobProfile)

  • New Methods:

    • void lockProfile(UUID jobProfileId)

    • void unlockProfile(UUID jobProfileId)

      • Unlocking requires special permissions.

  • Modified Methods:

    • void deleteJobProfileById(UUID jobProfileId)

    • void putJobProfile(UUID jobProfileId, JobProfile jobProfile)

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.

3. Controller Layer Modifications

Existing endpoints for updating job and mapping profiles should be used to lock/unlock. Locking/unlocking process should be considered as changing of lock field state.

Extend API Endpoints:

  • New Endpoints:

    • PUT /mapping-profiles/{mappingProfileId}

      • Description: Update a mapping profile (including locking/unlocking).

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

    • PUT /job-profiles/{jobProfileId}

      • Description: Update a job profile (including locking/unlocking).

      • Permissions Required: data-export.job-profiles.item.lock.execute, data-export.job-profiles.item.unlock.execute

  • Existing endpoints of JobProfileController should be switched to JobProfileService.

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.

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

    • Allows Users To: Lock a job profile.

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

    • Allows Users To: Unlock a job 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.

From technical perspective it is required to complete:

  1. Refactoring of JobProfileController to move existing logic in separate service JobProfileService because there are no service layer for current implementation.

  2. Updating of PUT methods for locking/unlocking logic for both mapping and job profiles in corresponding controllers.