Technical Documentation — Data Merging Component (OutSystems)

🔍 Overview

The Data Merging Component was developed to resolve data conflicts in real-time in OutSystems applications, where multiple users access and edit the same complex data structure simultaneously. It provides an automated merge process (similar to Service Studio), with support for manual conflict resolution when necessary.

🧩 Key Features

• Automatic data merging based on three versions: original, active (server), and edited.

• Conflict resolution similar to Service Studio, where the user can choose which value to keep.

• 100% front-end execution, reducing server load and improving performance.

• Lodash library usage for efficient manipulation of complex JSON objects.

• Reusable visual block for user conflict selection.

📂 Usage Flow

🧾 Required Structures

To perform the merging process, the user needs to provide the following three JSON objects as input in the MergeJSONVersion action:

• OriginalJSON – The original structure loaded on the screen.

• ActiveJSON – The most recent version of the structure saved on the server.

• NewJSON – The structure modified locally after the server version.

⚙️ Action: MergeJSONVersion

📥 Input Parameters:

• OriginalJSON: The original JSON initially loaded.

• ActiveJSON: The current version of the JSON saved on the server.

• NewJSON: The JSON with the modifications made locally by the user.

📤 Output Parameters:

• Return: A structure indicating whether the operation was successful or if an error occurred.

• MergedJSON: The resulting JSON after the merge, considering NewJSON changes as the default in case of conflicts.

• SimilarChanges: A list containing fields with similar/conflicting changes between ActiveJSON and NewJSON.

🧠 Merging Logic

• Different changes → automatic merge.

• Conflicts on the same fields → NewJSON's value takes precedence, unless the user opts to choose manually.

• The SimilarChanges list can be used to display a visual block with choices for the user.

🧱 Conflict Resolution Block: SimilarChanges

Name: SimilarChanges

A UI block that allows the end-user to visualize and choose the correct values for fields that have conflicts between ActiveJSON and NewJSON.

📥 Input Parameters:

• SimilarChanges: A list containing fields with similar or conflicting changes between ActiveJSON and NewJSON.

• OldJSON: The original JSON initially loaded.

• NewJSON: The JSON locally modified by the user.

• MergedJSON: The resulting JSON from the merge, containing the automatic merge changes.

📤 Output Event:

• ReturnNewJSON: Returns the final JSON with the values selected by the user for the conflicting fields.

🛠️ How to Use

1. Add the SimilarChanges block in a pop-up modal.

2. Execute the MergeJSONVersion(OriginalJSON, ActiveJSON, NewJSON) action.

3. Check the SimilarChanges list:

   • If there are conflicts, open the pop-up and pass the parameters to the block.

4. The user resolves the conflicts visually, and in the ReturnNewJSON event, the application receives the final adjusted JSON to be saved or processed as needed.

🧪 Practical Example of Use

Scenario:

• A form with hierarchical data (e.g., customer registration with contacts and preferences) is being edited by two users.

Step-by-Step:

1. User A loads the data and stores the OriginalJSON.

2. They make modifications and save, updating the ActiveJSON on the server.

3. User B, who still had the older structure loaded, modifies the data and creates their own NewJSON.

4. Before saving:

   • The application executes MergeJSONVersion(OriginalJSON, ActiveJSON, NewJSON).

   • The action returns:

     • MergedJSON: With the merged changes, considering NewJSON as the priority in conflicts.

     • SimilarChanges: A list of fields with similar changes in ActiveJSON and NewJSON.

5. If SimilarChanges is not empty:

   • The application opens the SimilarChanges block in a pop-up.

   • Pass the parameters: OldJSON, NewJSON, and MergedJSON.

   • The user selects the desired values.

6. The block returns the final JSON in the ReturnNewJSON event, which can then be saved or processed according to the business logic.

✅ Advantages

• Prevents accidental overwriting in collaborative environments.

• The merge logic on the front-end improves performance and user experience.

• Integration with Lodash makes the component robust and efficient for handling nested objects.

• The visual block makes conflict resolution easy and intuitive.

• Lightweight, reusable, and easy to maintain.